committing-with-guidelines

以故事为先的提交

构建一组便于审查的原子提交。每个提交都应记录一个产品或架构成果，并提供足够的理由，让未来的读者能够理解。

工作流

1. 检查工作区

至少检查：

git status --short
git diff
git diff --cached

如果仓库的约定可能比此技能更严格，请查看近期提交的主题。识别生成的文件、无关的编辑，以及应保持未提交状态的更改。

完成条件： 每个已更改路径都属于某个拟议提交，或已明确排除。

2. 规划故事线

按依赖关系以及审查者了解更改的顺序安排提交。每个提交只包含一个逻辑成果，同时纳入相关测试和文档。即使不相关的成果修改了同一个文件，也要拆分提交。

如果有多个提交，请在暂存之前说明拟议的顺序。

完成条件： 每个已更改的代码块都有唯一的归属，并且每个提交都能独立成立。

3. 暂存一个单元

暂存指定路径，或使用补丁模式：

git add path/to/file
git add -p

然后检查暂存结果：

git diff --cached --stat
git diff --cached

只有在检查完整个工作区后，才使用广泛暂存。

完成条件： 索引中恰好包含一个逻辑成果，以及支撑该成果所需的测试和文档。

4. 验证暂存的更改

运行仓库相关的测试、代码检查工具或其他检查。选择能够覆盖此提交的最精简检查；如果项目说明有要求，则增加更全面的检查。

完成条件： 所需检查全部通过；如果有检查失败，则让用户了解失败原因，以及是否应该继续提交。

5. 撰写并创建提交

使用以下结构：

<Action> <product-focused outcome>

- <decision, rationale, user impact, or trade-off>
- <additional context only when it helps a future reader>

主题

• 以 Add、Update、Remove 或 Delete 开头。
• 使用现在时，并说明具体成果。
• 主题最好不超过 72 个字符。
• 描述产品或架构，而不是文件或类。
• 除非仓库要求，否则将工单编号保留在分支名称中。

示例：

Add team filtering to the progress dashboard
Update notification delivery to support multiple channels
Remove deprecated user-preference endpoints

正文

如果 diff 无法明显体现更改的原因、影响或权衡，请添加正文。对于不同的决策，请使用项目符号说明。解释：

• 为什么采用这种更改方式；
• 对产品或用户的影响；
• 架构方面的影响；
• 重要的权衡。

省略实现清单、常规测试新增内容，以及 AI 归属或共同作者信息。diff 记录实现；提交消息记录意图。

提交前，再次阅读暂存的 diff，并根据其中的确切内容撰写提交消息。

完成条件： 提交消息准确描述暂存的成果及其不明显的原因。

6. 验证并继续

每次提交后，检查 git status --short 和新提交。针对下一个计划单元重复此工作流。

完成条件： 预期的提交顺序已创建，每个提交都能独立理解，剩余更改也都有明确归属。

历史安全

将已发布的历史视为不可变。只有在用户要求编辑历史并确认提交可以安全改写时，才重新排序、压缩、修改或强制推送。优先使用 --force-with-lease，而不是 --force。

如需了解拆分混合工作区、改进提交消息或整理未发布提交的实际示例，请阅读 EXAMPLES.md。