4.1 KiB
4.1 KiB
提交后强制推送 Gitea 设计规格
- 功能编号：GOV-004
- 规格版本：0.1
- 状态：approved_for_review
- 日期：2026-08-12
背景与目标
本地提交如果没有同步到远程，无法实现跨设备备份、Gitea 审阅和可靠的版本追溯。本功能把推送从“需要逐次授权的可选动作”改成项目开发流程的固定完成条件。
目标是：每次本地提交在验证通过后立即同步当前分支；创建版本标签后同步该标签；任何推送失败都会阻止任务被报告为完成。
方案比较
方案 A：按变化精确推送（采用）
- 普通提交执行
git push origin <当前分支>。 - 创建新标签后执行
git push origin <标签名>。 - 优点：只同步本次明确产生的引用，行为可预测，不会意外发布其他本地标签。
- 代价：分支和标签需要分别执行推送。
方案 B：每次提交推送分支及全部标签
- 执行
git push origin <当前分支> --tags。 - 优点：命令较少。
- 缺点：可能把尚未准备发布的历史或实验标签一并推送，不采用。
方案 C：仅发布时批量推送
- 多个本地提交积累到版本发布时再统一同步。
- 优点：减少远程交互次数。
- 缺点：提交期间缺少远程备份，也不符合“提交后需要推送”的要求，不采用。
强制流程
- 完成测试、构建、Review、GitNexus 变更检测和敏感信息检查。
- 创建符合中文 Conventional Commit 的本地提交。
- 获取当前分支名，执行
git push origin <当前分支>。 - 如果本次创建了标签，再执行
git push origin <标签名>。 - 使用
git status -sb或远程引用检查，确认本地分支与远程分支一致。 - 把提交 SHA、推送目标、推送结果和标签结果写入功能档案。
- 只有分支及本次新建标签全部推送成功后，任务才可以标记完成。
失败处理
- 认证、网络、分支保护或服务器错误发生时，保留本地提交和标签，不删除、不改写历史。
- 将任务状态标为“推送失败/未完成”，记录失败命令、时间和不包含凭据的错误摘要。
- 修复原因后重复同一个精确推送命令；禁止使用
--force、--force-with-lease或绕过保护规则。 - 远程出现未知提交导致非快进失败时，先获取并检查差异，不自动 rebase、merge 或覆盖远程。
- 密码和令牌继续由 macOS Keychain 管理，禁止写入文档、脚本、远程 URL、命令参数和 Git 历史。
配置与作用域
- 唯一允许的推送远程是当前项目
.git/config中的origin。 - 推送前必须验证
origin仍为https://git.foximao.com/FoXiMao/a-share-analysis.git。 - 禁止修改 Git 全局配置，禁止影响其他项目，禁止新增 GitHub 远程。
- 本规则适用于业务代码、治理文档、规格、Review 修正和版本封存等所有提交。
文档变更范围
AGENTS.md：把提交后推送改为代理强制要求。docs/governance/development-workflow.md：把推送加入开发后流程和完成定义。docs/governance/version-control-and-gitea.md：记录标准命令、失败处理和验证方法。README.md：简述项目提交会同步到 Gitea。docs/features/GOV-004-mandatory-gitea-push/：保存 PRD、需求、实施计划、测试、Review、GitNexus 前后对比、发布和回退证据。
GOV-003 是当时“只接入、不推送”的历史决策记录，保持原文不变；GOV-004 作为后续决策明确取代其推送授权规则，保证历史可追溯。
验收标准
- 所有现行入口规范不再包含“默认不推送”或“逐次取得用户授权”的冲突要求。
- 规范明确普通提交推当前分支、新标签单独推送、失败不算完成、禁止强推。
main的本地历史同步到origin/main。- 已有版本标签
v0.0.0、v0.0.1、v0.0.2同步到远程。 - GOV-004 的提交和后续封存标签也按相同规则同步。
- 全局 Git 配置保持不变，敏感信息扫描无发现。
- 治理测试、完成门禁和 GitNexus 前后检测通过。