79 lines
4.1 KiB
Markdown
79 lines
4.1 KiB
Markdown
# 提交后强制推送 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：仅发布时批量推送
|
|
|
|
- 多个本地提交积累到版本发布时再统一同步。
|
|
- 优点：减少远程交互次数。
|
|
- 缺点：提交期间缺少远程备份，也不符合“提交后需要推送”的要求，不采用。
|
|
|
|
## 强制流程
|
|
|
|
1. 完成测试、构建、Review、GitNexus 变更检测和敏感信息检查。
|
|
2. 创建符合中文 Conventional Commit 的本地提交。
|
|
3. 获取当前分支名，执行 `git push origin <当前分支>`。
|
|
4. 如果本次创建了标签，再执行 `git push origin <标签名>`。
|
|
5. 使用 `git status -sb` 或远程引用检查，确认本地分支与远程分支一致。
|
|
6. 把提交 SHA、推送目标、推送结果和标签结果写入功能档案。
|
|
7. 只有分支及本次新建标签全部推送成功后，任务才可以标记完成。
|
|
|
|
## 失败处理
|
|
|
|
- 认证、网络、分支保护或服务器错误发生时，保留本地提交和标签，不删除、不改写历史。
|
|
- 将任务状态标为“推送失败/未完成”，记录失败命令、时间和不包含凭据的错误摘要。
|
|
- 修复原因后重复同一个精确推送命令；禁止使用 `--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 前后检测通过。
|