jww-git-workflow

Git 工作流

请优先遵循仓库专属说明。将其视为分支名称、远程仓库、检查和拉取请求约定的权威依据。更改 Git 状态前，请先阅读这些说明。

本技能假定环境已提供通用的 Git 安全规则（保留无关工作、对破坏性远程更改先获得批准、原样保留 CLI 输出）。此外，还包括：

• 提交主题应说明交付的行为；如果差异中看不出原因，则应附上正文（参见“提交工作流”）
• 将功能分支变基到其基分支上，而不是合并基分支
• 通过修改相关的现有提交来处理拉取请求反馈，而不是创建后续提交
• 推送会重写已发布分支时，使用 --force-with-lease；覆盖之前先解决租约过期问题
• 推送经过验证的分支并创建或更新其 PR 属于常规步骤，无需单独批准；合并、删除及其他远程变更仍需批准

更改 Git 状态前

1. 检查 git status、当前分支和相关仓库说明。
2. 保留无关更改。未经所需批准，不得丢弃工作或清理历史记录。仅按提交工作流的指示修改提交。
3. 将探索性工作与已完成的实现分开。只暂存并提交后者。

提交工作流

1. 检查预期差异，并且只暂存属于已完成更改的文件。
2. 运行仓库要求的验证，并在提交前检查暂存区中的差异。
3. 确保每个提交内容聚焦一致。处理现有拉取请求或进行中的工作时，修改适用的现有提交，而不是添加后续提交，除非 Justin 或仓库约定要求单独提交。
4. 编写首字母大写的祈使句主题，描述交付的行为，而不是实现阶段或更改的文件。省略句末句号，长度控制在约 60 个字符以内。不要使用类型或范围前缀。
5. 如果差异中看不出原因，则添加正文。安全性、并发或默认值变更，以及移除或限制现有行为的更改，始终必须附带正文。先说明问题，再说明更改，最后说明读者需要了解的后果。提交正文每行不超过 72 列；不要逐一列出更改的文件。
6. 提交消息中不得将字面量 \\n 转义序列用作换行符。编写多行消息时，将实际换行写入临时文件，并使用 git commit --file 提交；提交后使用 git log -1 --format=%B 检查已保存的消息。
7. 如果提交解决了某个问题，请在最后一行恰好添加一个问题引用，例如 Closes #231 或 Fixes #253。不要提及助手、模型、Agent 或工具，也不要添加生成者声明。
8. 重写合并后的提交消息时，应描述已交付的功能，而不是最终工作检查点。

更新与发布

1. 将功能分支变基到其远程基分支上，而不是将基分支合并到功能分支，除非仓库明确要求这样做。
2. 推送前，确认分支、远程仓库以及将要推送的确切提交。
3. 如果推送经过验证的功能分支并创建或更新拉取请求即可完成 Justin 的请求，那么这些常规发布步骤无需单独批准。未经明确批准，不得合并、删除分支或标签、更改仓库设置，或执行其他破坏性远程变更。
4. 修改已发布分支上的提交时，只能使用 --force-with-lease 强制推送。如果租约已过期，请先获取并比较远程工作，再决定如何处理；保留等效或并行的工作，不要覆盖它。

Pull Requests 和 GitHub

1. 请先遵循仓库特定的拉取请求要求，再参考通用指南。
2. 原样保留对决策有影响的 Git 和 GitHub CLI 输出，尤其是错误信息和远程状态冲突。
3. 对于审查反馈、CI 失败或拉取请求分诊，请使用工具提供的 GitHub 集成或 gh CLI。不要声称连接器或 CLI 输出包含其未提供的信息。

审查和 CI 后续处理

根据当前差异、审查讨论和失败的检查输出，解决可操作的反馈。区分缺陷、过时的发现、已解决的发现和缺乏支持的发现，并提供证据说明为何驳回某项发现。

修复时使用 Commit Workflow。报告已解决的发现、仍存在的阻碍，以及与已发布版本关联的检查和反馈。排队中或正在运行的 CI 均属待处理；仅在本地验证并不能证明已准备好合并。除非收到要求，否则不要请求再次审查。

分支和工作树清理

根据当前远程和拉取请求证据，判断哪些分支和工作树已过时。考虑到 squash 或 rebase 合并：未出现在 Git 的已合并分支列表中，并不能证明更改尚未合并；拉取请求已关闭，也不能证明其更改已交付。已交付的分支仍可能是活跃工作的基准。报告保留的候选项及其原因。

拆分存在依赖关系的工作

产出可独立审查的结果，并明确其基准和实际依赖关系。重写历史记录前，保留可恢复的引用。需要分离时，将无关的工作树更改保留在独立分支或工作树中。

将每个结果的差异与其预期基准进行比较，检查是否缺少前置条件、存在重复更改或包含无关工作；并使用仓库的验证工作流验证每项受影响的结果。保留并说明阻碍功能独立运行的依赖关系。按照 Updating and Publishing 的要求，使已发布的拉取请求基准和描述与拆分结果保持一致。