Best Practices
发布前 Git 卫生专题
在发布前用一组 Git 检查动作降低标签、分支和版本记录出错概率。
- 希望把 Git 用得更稳的个人或团队
- 准备建立协作规范的维护者
- 至少有一次真实协作经验
- 知道常见命令但还没形成稳定习惯
- 把建议当硬规则而忽略上下文
- 只记流程，不理解背后的协作边界
为什么发布前最怕"差不多就行"
代码已冻结测试已通过changelog 待更新版本号待升级
语义化版本号 vX.Y.Zannotated tag + 签名changelog 按版本分组发布后验证清单
发布卫生不是流程负担，而是质量保障。每次发布都应该是可信赖的事件。
发布是一个高风险动作。 所以发布前 Git 卫生的目标不是多做流程，而是确保“这次发布到底对应哪段历史”这件事足够清楚。
1. 先确认你站在正确的分支和提交上
发布前至少先确认两件事：
git status
git log --oneline --decorate -5
你要能明确知道：
- 当前是否在预期的发布分支上
- 工作区是不是干净的
- 最近几次提交是否真的是本次要发布的内容
如果这一步都说不清，后面再打 tag 就是在给以后挖坑。
2. 标签一定要和具体提交绑定清楚
发布标签最怕两种问题：
- tag 打错提交
- tag 名称不稳定
更稳的习惯是先确认目标提交，再打注释标签：
git tag -a v1.4.0 -m "Release v1.4.0"
git show v1.4.0
git show 这一步很重要，它会让你看到 tag 最终到底落在了哪次提交上。
3. 发布前最好再核一次差异范围
除了看提交，还应该再看一次本次发布相对上一个版本到底改了什么。
一个很实用的检查方式是比较上个 tag 到当前 HEAD 的范围：
git diff --stat v1.3.0..HEAD
这样可以快速判断：
- 这次发布的范围是否符合预期
- 有没有混进不该发布的改动
- 发布说明和真实改动是否一致
4. 发布历史最好可追、可复盘
一个发布不是“发出去就结束”，以后你还会需要：
- 回答某个问题在哪个版本进入
- 对比两个版本之间的差异
- 回滚到某个稳定版本
所以发布时更稳的做法是：
- tag 命名一致
- 标签说明简洁明确
- 发布说明能和 Git 历史对上
5. 一个适合团队长期执行的发布前清单
可以收成下面这 5 步：
- 确认当前分支和工作区状态
- 看最近几条提交是否正确
- 检查本次发布范围
- 给正确提交打清晰的 tag
- 再次核对 tag 指向
这套动作很轻，但能显著降低发布后“版本记录讲不清”的问题。