From 2a16e9f7d1f74cf382cf31efb2817363e7210667 Mon Sep 17 00:00:00 2001 From: Citrons <909229731@qq.com> Date: Wed, 12 Aug 2026 18:43:17 +0800 Subject: [PATCH] =?UTF-8?q?docs(GOV-004):=20=E5=BC=BA=E5=88=B6=E6=8F=90?= =?UTF-8?q?=E4=BA=A4=E5=90=8E=E5=90=8C=E6=AD=A5=20Gitea?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 4 +- CHANGELOG.md | 6 +++ README.md | 2 + VERSION | 2 +- .../gitnexus/after.md | 9 ++++ .../gitnexus/comparison.md | 10 +++++ .../gitnexus/detected-changes.md | 9 ++++ .../gitnexus/impact-plan.md | 9 ++++ .../manifest.yaml | 17 +++++++ .../GOV-004-mandatory-gitea-push/prd.md | 44 ++++++++++++++++++ .../qa/test-results.md | 24 ++++++++++ .../qa/visual-qa.md | 3 ++ .../release-notes.md | 9 ++++ .../requirements.md | 13 ++++++ .../review/code-review.md | 35 +++++++++++++++ .../review/standards-review.md | 25 +++++++++++ .../GOV-004-mandatory-gitea-push/rollback.md | 12 +++++ .../GOV-004-mandatory-gitea-push/test-plan.md | 13 ++++++ docs/governance/development-workflow.md | 22 +++++++-- docs/governance/version-control-and-gitea.md | 45 +++++++++++++++++-- docs/index.md | 1 + 21 files changed, 304 insertions(+), 10 deletions(-) create mode 100644 docs/features/GOV-004-mandatory-gitea-push/gitnexus/after.md create mode 100644 docs/features/GOV-004-mandatory-gitea-push/gitnexus/comparison.md create mode 100644 docs/features/GOV-004-mandatory-gitea-push/gitnexus/detected-changes.md create mode 100644 docs/features/GOV-004-mandatory-gitea-push/gitnexus/impact-plan.md create mode 100644 docs/features/GOV-004-mandatory-gitea-push/manifest.yaml create mode 100644 docs/features/GOV-004-mandatory-gitea-push/prd.md create mode 100644 docs/features/GOV-004-mandatory-gitea-push/qa/test-results.md create mode 100644 docs/features/GOV-004-mandatory-gitea-push/qa/visual-qa.md create mode 100644 docs/features/GOV-004-mandatory-gitea-push/release-notes.md create mode 100644 docs/features/GOV-004-mandatory-gitea-push/requirements.md create mode 100644 docs/features/GOV-004-mandatory-gitea-push/review/code-review.md create mode 100644 docs/features/GOV-004-mandatory-gitea-push/review/standards-review.md create mode 100644 docs/features/GOV-004-mandatory-gitea-push/rollback.md create mode 100644 docs/features/GOV-004-mandatory-gitea-push/test-plan.md diff --git a/AGENTS.md b/AGENTS.md index 48da0ff..07e2f7b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,12 +18,12 @@ 7. 不使用 GitHub。本项目唯一远程仓库为项目级配置的 Gitea `https://git.foximao.com/FoXiMao/a-share-analysis.git`；禁止修改 Git 全局配置或影响其他项目。 8. 禁止提交密钥、密码、访问令牌、生产数据、`.env` 和 GitNexus 本地索引；凭据不得写入远程 URL、文档、脚本或命令参数。 9. 开发完成后必须先通过代码 Review 和开发规范符合性 Review，再进入发布；Review 结论和问题处置必须写入功能档案。 -10. 添加远程不等于获得推送授权；除非用户明确要求，不得主动向 Gitea 推送提交或标签。 +10. 每次提交验证通过后必须立即推送当前分支到项目 Gitea；本次新建标签必须单独推送。推送失败时任务不得标记完成，禁止强推或自动覆盖未知远程提交。 # GitNexus — Code Intelligence -This project is indexed by GitNexus as **a-share-analysis** (361 symbols, 387 relationships, 0 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. +This project is indexed by GitNexus as **a-share-analysis** (432 symbols, 458 relationships, 0 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first. diff --git a/CHANGELOG.md b/CHANGELOG.md index 38efd59..2e5fcc2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ 本项目采用语义化版本。功能级变化请从 `docs/features/` 按功能编号追溯。 +## 0.0.3 - 2026-08-12 + +- 将当前分支推送设为每次提交后的强制步骤，新标签采用精确推送。 +- 将远程同步成功加入完成定义，明确失败留痕、禁止强推和远程引用核对规则。 +- GOV-004 取代 GOV-003 的“只接入、不主动推送”历史规则，但保留原档案用于追溯。 + ## 0.0.2 - 2026-08-12 - 配置仅作用于本项目的 Gitea 远程仓库和凭据隔离策略。 diff --git a/README.md b/README.md index 4d9cade..73cbcc8 100644 --- a/README.md +++ b/README.md @@ -36,3 +36,5 @@ npm run governance:start -- FEAT-MO-001 market-overview 凭据不写入仓库、文档或远程 URL。首次需要认证时由 Git 调用 macOS Keychain 安全保存；详细规则见 [Git 与 Gitea 规范](docs/governance/version-control-and-gitea.md)。 + +验证通过的中文提交必须立即同步当前分支到 Gitea；本次创建的版本标签单独同步。远程同步失败时，开发任务保持未完成状态。 diff --git a/VERSION b/VERSION index 4e379d2..bcab45a 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.0.2 +0.0.3 diff --git a/docs/features/GOV-004-mandatory-gitea-push/gitnexus/after.md b/docs/features/GOV-004-mandatory-gitea-push/gitnexus/after.md new file mode 100644 index 0000000..ec415b0 --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/gitnexus/after.md @@ -0,0 +1,9 @@ +# GitNexus 开发后结果 + +- 执行：`npx gitnexus analyze`。 +- 开发后工作区索引：426 个节点、452 条关系、5 个集群、0 条执行流程。 +- 增量分析：6 个已修改文件、17 个新增文件、0 个删除文件；75 个未变化文件行复用既有索引。 +- 当前索引提交：`2d2502c`，工作区文档变化已进入增量图谱。 +- 状态：up-to-date。 + +本功能没有修改生产代码、函数调用关系或业务执行流程。实现提交后再次分析，把最终索引锚定到确定提交。 diff --git a/docs/features/GOV-004-mandatory-gitea-push/gitnexus/comparison.md b/docs/features/GOV-004-mandatory-gitea-push/gitnexus/comparison.md new file mode 100644 index 0000000..72bd466 --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/gitnexus/comparison.md @@ -0,0 +1,10 @@ +# GitNexus 前后对比 + +| 项目 | 开发前 | 开发后工作区 | 变化 | +|---|---:|---:|---:| +| 节点 | 361 | 426 | +65 | +| 关系 | 387 | 452 | +65 | +| 集群 | 5 | 5 | 0 | +| 执行流程 | 0 | 0 | 0 | + +增长来自 GOV-004 的规格、实施计划、现行治理入口和追溯档案。执行流程保持为 0，符合开发前“只影响治理文档与远程同步流程”的预估。 diff --git a/docs/features/GOV-004-mandatory-gitea-push/gitnexus/detected-changes.md b/docs/features/GOV-004-mandatory-gitea-push/gitnexus/detected-changes.md new file mode 100644 index 0000000..9c8ba8c --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/gitnexus/detected-changes.md @@ -0,0 +1,9 @@ +# GitNexus 变更检测 + +- 初次工作区命令：`npx gitnexus detect-changes --repo a-share-analysis --scope all`。 +- 初次识别：7 个既有文件、16 个文档符号。 +- 最终暂存区识别：21 个文件、44 个文档符号。 +- 受影响流程：0。 +- 风险等级：低。 + +完整暂存后使用 `--scope staged` 将 GOV-004 新建档案纳入检测；最终结果仍为 0 条受影响流程、低风险。 diff --git a/docs/features/GOV-004-mandatory-gitea-push/gitnexus/impact-plan.md b/docs/features/GOV-004-mandatory-gitea-push/gitnexus/impact-plan.md new file mode 100644 index 0000000..da30bbd --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/gitnexus/impact-plan.md @@ -0,0 +1,9 @@ +# GitNexus 开发前影响分析 + +- 查询主题：`mandatory push after commit Gitea workflow`。 +- 主要关联：GOV-003 功能档案、`docs/governance/version-control-and-gitea.md`、`docs/governance/development-workflow.md`、`AGENTS.md`、`README.md` 和文档索引。 +- 查询没有返回业务执行流程，说明变化不触及前端、后端、数据任务或运行时调用链。 +- 本次不修改函数、类或方法，因此不存在需要符号级上游影响分析的生产代码目标。 +- 预计影响：开发完成定义、远程同步授权规则、标签发布规则、版本号和治理档案。 +- 风险：文档冲突可能让代理继续遵循旧规则；通过限定扫描现行治理入口并保留 GOV-003 为历史记录解决。 +- 外部状态风险：推送改变 Gitea；用户已经明确授权，并要求此后把推送设为固定开发步骤。 diff --git a/docs/features/GOV-004-mandatory-gitea-push/manifest.yaml b/docs/features/GOV-004-mandatory-gitea-push/manifest.yaml new file mode 100644 index 0000000..d5ab4c5 --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/manifest.yaml @@ -0,0 +1,17 @@ +id: GOV-004 +name: 提交后强制推送 Gitea +slug: mandatory-gitea-push +status: verifying +owner: project +created_at: 2026-08-12 +prd: prd.md +requirements: requirements.md +design: design.md +implementation_plan: implementation-plan.md +gitnexus_before: gitnexus/before.md +gitnexus_after: gitnexus/after.md +gitnexus_comparison: gitnexus/comparison.md +code_review: review/code-review.md +standards_review: review/standards-review.md +implementation_commit: pending +release: v0.0.3 diff --git a/docs/features/GOV-004-mandatory-gitea-push/prd.md b/docs/features/GOV-004-mandatory-gitea-push/prd.md new file mode 100644 index 0000000..a866a39 --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/prd.md @@ -0,0 +1,44 @@ +# 提交后强制推送 Gitea PRD + +- 功能编号：GOV-004 +- PRD 版本：0.1 +- 状态：approved +- 日期：2026-08-12 + +## 问题 + +项目此前只要求保存本地提交，是否推送需要逐次确认。这会导致本地版本与 Gitea 长期不一致，使远程备份、跨设备读取、历史审阅和版本回退缺少可靠依据。 + +## 目标 + +- 每次验证通过的本地提交立即推送当前分支。 +- 本次创建的新标签在分支推送成功后单独推送。 +- 推送失败时任务保持未完成，并提供安全、可审计的重试路径。 +- 让提交、远程分支、标签和功能档案保持可核对的一致关系。 + +## 非目标 + +- 不自动推送其他本地分支或非本次创建的标签。 +- 不使用强推，不自动合并、rebase 或覆盖未知远程提交。 +- 不新增 GitHub、CI、Webhook 或 Gitea 服务端配置。 +- 不修改全局 Git 配置，不影响其他项目。 + +## 用户流程 + +开发者完成验证与 Review 后创建中文提交，随即把当前分支推送到项目 `origin`；若同时发布版本，则精确推送新标签。系统核对远程 SHA 并在功能档案中记录结果。任何环节失败都保留本地状态，解决原因后重试，不能对外宣称完成。 + +## 验收标准 + +- 现行规范明确普通提交只推当前分支，新标签只推本次创建的标签。 +- 现行规范明确推送成功属于完成定义，失败必须留痕并阻断完成。 +- 现行规范禁止 `--force`、`--force-with-lease`、自动覆盖或自动改写远程历史。 +- `origin/main` 与最终本地 `main` SHA 一致。 +- 既有 `v0.0.0`、`v0.0.1`、`v0.0.2` 以及新 `v0.0.3` 标签均能从远程读取并对应本地标签提交。 +- 凭据继续由 macOS Keychain 管理，仓库和提交历史无密码或令牌。 +- 全局 Git 配置保持不变，治理门禁和 GitNexus 变更检测通过。 + +## 风险 + +- 远程网络或认证故障会延迟任务完成，但不会破坏本地提交。 +- 分支保护或远程出现未知提交时可能拒绝推送；必须停下检查，不得绕过保护。 +- 将所有标签批量推送可能发布未批准标签，因此只允许精确推送指定标签。 diff --git a/docs/features/GOV-004-mandatory-gitea-push/qa/test-results.md b/docs/features/GOV-004-mandatory-gitea-push/qa/test-results.md new file mode 100644 index 0000000..20c71a8 --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/qa/test-results.md @@ -0,0 +1,24 @@ +# 测试结果 + +## 本地验证 + +- `npm run test:governance`：5 个测试通过，0 个失败。 +- `git diff --check`：通过。 +- 现行推送规则冲突扫描：无匹配。 +- `origin` push URL：精确匹配项目 Gitea。 +- 项目配置：Keychain、路径隔离、账号和默认推送目标均符合设计。 +- 全局边界：全局 `credential.helper` 和 `remote.pushDefault` 保持未设置。 +- 敏感信息扫描：未发现凭据 URL、密码赋值或令牌赋值。 +- GitNexus：426 个节点、452 条关系、5 个集群、0 条流程；变更风险为低。 +- GitNexus 最终暂存区：21 个文件、44 个符号、0 条流程，风险为低。 +- `npm run governance:finish -- GOV-004 mandatory-gitea-push`：退出码 0，完整档案和双 Review 门禁通过。 + +## 诊断记录 + +初次冲突扫描命中新规范中的否定说明“不再逐次请求推送授权”。该文本并未要求逐次授权，但会让机器扫描误报，因此改写为“用户已授予本项目持续推送权限”；同一扫描复测无匹配。 + +## 远程同步 + +- 设计提交 `757d8ab` 已推送，首次建立 `origin/main`。 +- 计划提交 `2d2502c` 已推送，并验证远程 `main` 与本地 SHA 一致。 +- 实现提交、历史标签和 `v0.0.3` 的同步结果在创建相应引用后回填。 diff --git a/docs/features/GOV-004-mandatory-gitea-push/qa/visual-qa.md b/docs/features/GOV-004-mandatory-gitea-push/qa/visual-qa.md new file mode 100644 index 0000000..406c666 --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/qa/visual-qa.md @@ -0,0 +1,3 @@ +# 视觉验证 + +本功能只修改 Git/Gitea 流程与治理文档，不改变页面、样式、图表或交互，因此视觉验证不适用。 diff --git a/docs/features/GOV-004-mandatory-gitea-push/release-notes.md b/docs/features/GOV-004-mandatory-gitea-push/release-notes.md new file mode 100644 index 0000000..7075aae --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/release-notes.md @@ -0,0 +1,9 @@ +# 发布说明 + +## v0.0.3 + +- 把当前分支推送设为每次提交后的固定完成步骤。 +- 本次创建的新标签采用精确推送，禁止用 `--tags` 批量发布其他标签。 +- 推送失败将阻断任务完成，并禁止强推或自动覆盖未知远程历史。 +- 增加远程 SHA 核对与功能档案留痕要求。 +- GOV-004 取代 GOV-003 的旧推送授权规则，历史档案保持不变。 diff --git a/docs/features/GOV-004-mandatory-gitea-push/requirements.md b/docs/features/GOV-004-mandatory-gitea-push/requirements.md new file mode 100644 index 0000000..cacd7dd --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/requirements.md @@ -0,0 +1,13 @@ +# 工程需求 + +- 提交前必须完成测试、构建或适用性说明、双 Review、GitNexus 变更检测及敏感信息检查。 +- 提交信息必须使用中文 Conventional Commit 并包含功能编号。 +- 提交后读取当前分支名，执行 `git push origin <当前分支>`。 +- 创建新标签后执行 `git push origin <标签名>`，禁止使用 `--tags` 代替精确推送。 +- 推送完成后比较本地分支 SHA 与 `git ls-remote origin refs/heads/<当前分支>`。 +- 标签核对必须解析带注释标签指向的提交，而不是只比较标签对象 SHA。 +- 推送失败时保留本地提交，记录不含凭据的错误摘要并阻断任务完成。 +- 禁止 `--force`、`--force-with-lease`、自动 rebase、自动 merge 和覆盖未知远程引用。 +- 唯一远程必须是本项目 `.git/config` 中的指定 `origin`，不得修改全局 Git 配置。 +- 密码和令牌只能由系统 Keychain 管理，不得进入项目文件、Git URL、命令参数和 Git 历史。 +- GOV-003 保留原始历史文本；现行推送规则以 GOV-004 和治理入口为准。 diff --git a/docs/features/GOV-004-mandatory-gitea-push/review/code-review.md b/docs/features/GOV-004-mandatory-gitea-push/review/code-review.md new file mode 100644 index 0000000..402f938 --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/review/code-review.md @@ -0,0 +1,35 @@ +# 配置与文档 Review + +- reviewer_type：self +- reviewer：Codex +- 基线提交：`4b390d9` +- 设计提交：`757d8ab` +- 计划提交：`2d2502c` +- 实现提交：`pending` +- 审查范围：强制推送流程、远程核对、失败处理、版本同步和功能档案 +- 日期：2026-08-12 + +## PRD 与设计符合性 + +现行规范已经覆盖当前分支立即推送、新标签精确推送、失败阻断完成、禁止强推、远程 SHA 核对、Keychain 凭据边界和功能档案留痕。GOV-003 保持原文，GOV-004 明确取代其旧推送授权规则。 + +## 发现与处置 + +| 严重程度 | 发现 | 处置 | +|---|---|---| +| Important | 原 `AGENTS.md` 和开发流程仍要求逐次获得推送授权，与用户新要求冲突 | 现行入口统一改为持续授权和提交后强制推送，并增加冲突文本扫描 | +| Important | 批量 `--tags` 可能发布无关标签 | 明确只允许 `git push origin <本次标签名>`，并把禁止 `--tags` 写入规范 | +| Important | 推送失败后自动强推、合并或 rebase 可能破坏未知远程历史 | 明确失败阻断完成、先检查差异以及禁止强推和自动改写 | +| Minor | 新规范中的否定句触发冲突扫描误报 | 改为肯定式持续授权声明，复测无冲突匹配 | + +## 验证 + +- 5 个治理测试通过，`git diff --check` 通过。 +- 现行规则冲突扫描和敏感信息扫描通过。 +- Git 配置仅位于当前项目，全局相关配置保持未设置。 +- GitNexus 最终暂存区检测为 21 个文件、44 个符号、0 条流程、低风险。 +- 设计和计划两次提交均已按新规则推送并核对远程 `main`。 + +实现提交和标签引用将在创建后按规范精确推送，不存在阻断提交的 Review 问题。 + +最终结论：passed diff --git a/docs/features/GOV-004-mandatory-gitea-push/review/standards-review.md b/docs/features/GOV-004-mandatory-gitea-push/review/standards-review.md new file mode 100644 index 0000000..a1fedf6 --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/review/standards-review.md @@ -0,0 +1,25 @@ +# 开发规范符合性 Review + +- reviewer_type：self +- reviewer：Codex +- 实现提交：`pending` +- 日期：2026-08-12 + +## 检查结果 + +- [x] 用户批准设计规格后才进入实施。 +- [x] 开发前运行治理启动、GitNexus 查询并保存基线。 +- [x] PRD、工程需求、设计、计划、测试和回退说明一致。 +- [x] GOV-003 历史原文未被篡改，后续决策通过 GOV-004 追溯。 +- [x] 现行入口没有相互冲突的推送授权规则。 +- [x] 未修改生产代码，没有不必要的代码拆分或依赖变化。 +- [x] 未配置 GitHub，唯一远程仍为项目专用 Gitea。 +- [x] 未修改 Git 全局配置，密码和令牌未进入仓库。 +- [x] 治理测试、文档检查、GitNexus 和敏感信息扫描通过。 +- [x] 界面没有变化，视觉验证合理标记为不适用。 + +## 不符合项与处置 + +没有未解决的 Critical 或 Important 不符合项。最终分支和标签同步属于提交后的发布步骤，将通过远程引用比较闭环。 + +最终结论：passed diff --git a/docs/features/GOV-004-mandatory-gitea-push/rollback.md b/docs/features/GOV-004-mandatory-gitea-push/rollback.md new file mode 100644 index 0000000..65868ea --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/rollback.md @@ -0,0 +1,12 @@ +# 回退说明 + +本功能已经把 `main` 同步到共享 Gitea，因此不得使用 reset、强推或删除共享提交回退。 + +如果强制推送规则需要撤销： + +1. 创建新的治理功能编号并说明撤销原因。 +2. 使用中文修复提交恢复治理入口文字，不修改 GOV-004 历史档案。 +3. 通过完整测试、Review 和 GitNexus 门禁后正常推送修复提交。 +4. 已共享的 `v0.0.3` 标签不得移动或删除；使用新的补丁版本表达修正。 + +认证或网络故障不需要回退本地提交。保留提交，修复连接后重试精确推送；禁止将密码写入诊断记录。 diff --git a/docs/features/GOV-004-mandatory-gitea-push/test-plan.md b/docs/features/GOV-004-mandatory-gitea-push/test-plan.md new file mode 100644 index 0000000..d4b1380 --- /dev/null +++ b/docs/features/GOV-004-mandatory-gitea-push/test-plan.md @@ -0,0 +1,13 @@ +# 测试计划 + +- 运行 `npm run test:governance`，要求 5 个治理测试通过、0 个失败。 +- 运行 `git diff --check`，要求无空白错误。 +- 扫描 `AGENTS.md`、`README.md` 和 `docs/governance/`，要求不存在“默认不推送”或“逐次授权后才能推送”的现行冲突文本。 +- 检查 `git remote get-url --push origin` 精确等于指定 Gitea 仓库。 +- 比较 `git rev-parse main` 与远程 `refs/heads/main` SHA。 +- 分别解析本地和远程 `v0.0.0`、`v0.0.1`、`v0.0.2`、`v0.0.3` 指向的提交并比较。 +- 检查全局 `credential.helper` 和 `remote.pushDefault` 与 GOV-004 开始前一致。 +- 扫描仓库文件和暂存区，要求没有凭据 URL、密码赋值或令牌赋值。 +- 运行 `npx gitnexus analyze` 和指定仓库的 `detect-changes`，记录节点、关系、流程和风险。 +- 运行 `npm run governance:finish -- GOV-004 mandatory-gitea-push`，要求退出码为 0。 +- 本功能不修改页面，视觉验证标记不适用并说明原因。 diff --git a/docs/governance/development-workflow.md b/docs/governance/development-workflow.md index 5765789..e94c44c 100644 --- a/docs/governance/development-workflow.md +++ b/docs/governance/development-workflow.md @@ -59,9 +59,10 @@ npm run governance:finish -- FEAT-MO-001 market-overview 8. 逐条执行开发规范符合性 Review，将结果写入 `review/standards-review.md`。 9. 任一 Review 为 `changes_required` 时，返回开发阶段；修复后重跑相关测试、GitNexus开发后分析和 Review。 10. 两项 Review 均为 `passed` 后，更新发布说明、回退说明、变更记录和版本号。 -11. 使用中文 Conventional Commit提交。 -12. 提交后执行 `npx gitnexus status`；若状态过期，再运行 `npx gitnexus analyze`。 -13. 本地提交和标签完成后仍不得自动推送；只有用户明确要求时，才向项目专用 Gitea `origin` 推送。 +11. 使用中文 Conventional Commit 提交。 +12. 提交后立即将当前分支推送到项目专用 Gitea `origin`；如果本次创建了标签，再精确推送该标签。 +13. 比较本地与远程分支 SHA，并将提交、推送目标和结果写入功能档案。推送失败时保留本地提交，任务状态保持未完成。 +14. 提交后执行 `npx gitnexus status`；若状态过期，再运行 `npx gitnexus analyze`。 ## 6. 完成定义 @@ -77,6 +78,7 @@ npm run governance:finish -- FEAT-MO-001 market-overview - 开发规范符合性 Review 结论为 `passed`。 - 发布说明和回退方法可执行。 - 中文提交已关联功能编号。 +- 当前分支和本次新建标签已推送到 `origin`，功能档案保存远程核对结果。 ## 7. 提交流程 @@ -96,6 +98,20 @@ docs(GOV-001): 建立工程治理与追溯规范 一次提交应表达一个完整意图，但不为了追求小提交把同一功能切成无法独立理解的碎片。 +提交后推送当前分支： + +```bash +git push origin "$(git branch --show-current)" +``` + +如果本次创建了标签，只推送该标签： + +```bash +git push origin <本次标签名> +``` + +禁止使用 `--force`、`--force-with-lease` 或 `--tags` 代替精确推送。推送失败时不得宣称任务完成；应记录不含凭据的错误摘要，排查后重试同一精确命令。 + ## 8. 发布与回退 - 使用语义化版本和带注释 Git Tag。 diff --git a/docs/governance/version-control-and-gitea.md b/docs/governance/version-control-and-gitea.md index 903672e..f3ec3ed 100644 --- a/docs/governance/version-control-and-gitea.md +++ b/docs/governance/version-control-and-gitea.md @@ -48,15 +48,50 @@ git config --local remote.pushDefault origin GIT_TERMINAL_PROMPT=0 git ls-remote origin ``` -首次需要写权限时，由用户在交互式终端执行推送并输入凭据： +首次需要写权限时，在交互式终端推送并输入凭据： ```bash git push -u origin main ``` -添加远程和验证连通性不代表授权自动推送。代理只有在用户明确要求推送时才能执行。建议在 Gitea 中保护 `main`：禁止强推、要求状态检查通过、要求变更说明关联功能编号。 +首次认证完成后，凭据由 macOS Keychain 管理。GOV-004 起，用户已授予本项目持续推送权限，验证通过的提交必须立即推送。建议在 Gitea 中保护 `main`：禁止强推、要求状态检查通过、要求变更说明关联功能编号。 -## 4. 配置检查与移除 +## 4. 提交后强制推送 + +普通提交只推送当前分支： + +```bash +git push origin "$(git branch --show-current)" +``` + +本次创建版本标签时，在分支推送成功后精确推送该标签： + +```bash +git push origin <本次标签名> +``` + +不得使用 `git push --tags` 替代精确标签推送，避免发布其他未确认标签。不得使用 `--force` 或 `--force-with-lease`。 + +分支推送后核对远程 SHA： + +```bash +current_branch="$(git branch --show-current)" +git rev-parse "$current_branch" +git ls-remote origin "refs/heads/$current_branch" +``` + +两条结果必须指向相同提交。带注释标签核对时，应比较标签最终指向的提交，而不是标签对象本身。 + +如果认证、网络、分支保护或非快进检查导致推送失败： + +1. 保留本地提交和标签，不删除、不 amend、不重写历史。 +2. 记录失败命令、时间和不包含凭据的错误摘要，将任务标记为未完成。 +3. 先获取并审查远程差异；禁止自动 merge、rebase、强推或覆盖未知提交。 +4. 解决原因后重试同一个精确推送命令，并重新核对远程引用。 + +提交 SHA、远程分支、推送结果和本次标签结果必须写入对应功能档案。 + +## 5. 配置检查与移除 检查当前项目和全局配置的边界： @@ -80,7 +115,7 @@ git config --local --unset remote.pushDefault 上述操作只影响本项目。Keychain 中已保存的凭据需要在“钥匙串访问”中按 `git.foximao.com` 单独删除。 -## 5. 版本与标签 +## 6. 版本与标签 发布使用带注释标签，例如： @@ -89,3 +124,5 @@ git tag -a v0.1.0 -m "发布市场综合概览 v0.1.0" ``` 标签必须指向通过验证的提交。应用回退优先选择既有标签和不可变构建产物，而不是重新拼装旧版本。 + +本规范的强制推送规则由 GOV-004 建立，并取代 GOV-003 中“只接入、不主动推送”的历史规则；GOV-003 原文保留用于审计当时决策。 diff --git a/docs/index.md b/docs/index.md index 18b23da..3b9c2f7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -27,5 +27,6 @@ - [FEAT-MO-001：市场综合概览](features/FEAT-MO-001-market-overview/manifest.yaml) - [GOV-002：PRD 与 Review 门禁](features/GOV-002-prd-review-gates/manifest.yaml) - [GOV-003：项目专用 Gitea 远程仓库](features/GOV-003-gitea-local-remote/manifest.yaml) +- [GOV-004：提交后强制推送 Gitea](features/GOV-004-mandatory-gitea-push/manifest.yaml) 功能档案是需求、设计、代码、测试、版本和回退之间的唯一正式关联入口。