深圳团队周五发布前：七步写清跨时区提交说明

假设你在深圳，准备周五下午发布；另一位维护者要等几个小时才上线。对方看到“修一下那个问题”，只能重新翻代码、找工单，甚至等你回复。好的提交说明不需要漂亮文笔，而要让不在现场、母语不同的人知道：改了什么，为什么改，以及哪里需要留意。打开终端，选一项真实修改，按下面七步完成。

1. 从暂存区确认这次提交的边界

先运行 git diff --staged，逐个检查准备提交的文件，不要只看编辑器里最后打开的页面。如果同时包含登录修复、按钮颜色调整和无关格式化，先拆开。一次提交最好围绕一个能独立解释的目的；否则，无论标题多简洁，读者都难以判断哪些改动必须一起保留。

2. 按仓库约定选择共同语言

查看最近二十条提交和贡献说明，确认团队约定使用哪种语言、是否要求类型前缀。面向国际团队不等于每句话都要复杂英文，也不等于擅自改变仓库语言。使用大家能阅读的共同语言，保留准确的接口名和文件名，避免在一句话中随意切换多种语言。

3. 用对象和动作写出具体标题

先回答“哪个对象发生了什么变化”，再写标题。不要写“优化体验”，可以写“结账页在请求超时后显示重试入口”。前者无法帮助搜索，后者能让维护者快速定位行为变化。把最有辨识度的对象放在前面，并在终端日志里检查是否容易扫读；不要为了凑固定字数删掉关键条件。

4. 在正文补齐原因与行为差异

标题之后空一行，用短句说明旧行为、新行为和修改原因。例如：“此前请求超时后只显示错误提示，用户无法再次提交。现在保留已填内容并显示重试入口，避免用户重新输入。”不要逐行复述差异；代码能展示实现，提交正文应该补充代码本身无法表达的决策背景。

• 关联工单时，同时概括问题，不要只贴编号。
• 如果改变默认值、配置或调用方式，明确写出受影响对象。
• 区分已完成验证与尚未验证，不把预期效果写成事实。

5. 删掉依赖本地语境的表达

搜索标题和正文里的“这里”“之前那个”“正常了”等词，把它们换成具体页面、状态或条件。删掉俚语、双关和只有本地同事才懂的缩写。涉及日期时写明年月日；涉及时刻时补上时区。阅读者不应为了理解一次提交，先猜测作者所在城市的工作习惯。

6. 用模型检查歧义而不添加事实

如果经常需要跨语言润色，可以考虑按量付费的 RelayVano，通过同一入口调用模型辅助检查提交说明，并注册账号试用。只提交允许外发的脱敏文本，要求模型标出含糊指代、难懂缩写和过长句子，同时保留技术标识符，不得补写测试结果。逐项核对建议，模型不知道你实际执行过哪些验证。

7. 在提交前完成一次交接式复读

把自己当成刚接班的维护者，只读说明，不看聊天记录：能否知道改动对象、修改动机和注意事项？随后用 git diff --staged 再核对一次内容，确认没有遗漏配置变化，也没有声称未做过的测试。提交后用 git log -1 检查显示效果。目标不是让说明看起来专业，而是让下一位同事无需等你上线，也能继续工作。