5.4 版本控制与提交信息

5.4 版本控制与提交信息

本节摘要：版本控制实践是代码规范的重要组成部分：提交历史是写给未来的排查档案。本节讲约定式提交的格式与价值（类型加范围加描述）、小步提交的粒度判断、分支策略的选型考量，以及提交信息为什么要在"为什么"层面描述改动。

读前必看（上）

阅读完本节，你应当能够：

1. 按约定式提交格式书写提交信息并说明其机器可解析价值
2. 把握小步提交的粒度：一次提交一个逻辑变更
3. 比较常见分支策略的适用场景
4. 用提交历史辅助故障定位与回溯
5. 避免污染历史的常见操作（巨型提交、含混信息）

一、问题与直觉：一行"修改了一些问题"值多少钱

深夜排查一个线上回归：昨天还好的功能今天挂了。思路是"找出最近哪个提交引入的"——翻提交历史，看到的却是一片考古废墟：修改了一些问题、fix、更新代码、临时、最终版这次真的可以了，还有个三千行的巨型提交把二十个功能、一次依赖升级和半次重构焊在一起。二分定位失效了（提交粒度太粗，一刀切下去一半系统），只能人肉读三千行差异。一次本该十分钟的回溯，变成一晚上的阅读理解。

这就是提交规范缺失的账单。提交历史的本质是项目的事件日志：每个提交是一条"何时、何人、为何、改了什么"的记录。日志写得清楚，未来的一切回溯（找回归源头、理解某功能为何这样设计、审计合规）都快；写得含混，历史虽然都在，却等于加密存储——只有作者本人握有密钥，而作者早忘了。

二、核心原理：信息、粒度、分支

2.1 提交信息：约定式提交

推荐业界广泛采用的约定式提交格式：类型（可选范围）：简短描述，需要时补正文说明动机。常见类型固定成一个小集合：

feat: 新功能
fix: 缺陷修复
refactor: 重构（不改行为）
test: 测试
docs: 文档
chore: 构建 配置 杂务
​

示例对照：

# 差 描述了"动了"没描述"为何"与"何物"
fix: 修改了一些问题

# 好 一行看懂动机与对象 需要时正文展开
fix: 修复会员折扣叠加时总价为负的问题

  会员折上折场景下折扣系数相乘可能超过一，
  导致总价为负。改为折扣封顶至成本价之上。
​

约定式格式的两重价值。给人：历史列表可扫读——找某个功能的引入提交，过滤 feat 类型一眼即中；标题说不清的动机放正文，"为什么"层面永久留痕。给机器：类型是结构化字段，可以自动生成变更日志、自动判定版本号增量（缺陷修复对应补丁号、新功能对应次版本号）、按类型触发不同流水线。含混信息两头收益全失。

2.2 粒度：一次提交一个逻辑变更

小步提交的意思不是"每写十行提交一次"，而是每个提交是一个完整、自洽、可独立理解的逻辑变更。判断标准：这个提交的信息能用一句话说清吗；单独回滚它安全吗；它混入无关文件了吗。三种典型污染要避免：功能与格式化混提（第 2.3 节讲过，格式化独立成 commit）；多特性混提（拆成多个提交，各自带信息）；半成品提交（改了一半不能运行的代码，破坏"每个提交都应可用"的假设——二分定位正是建立在这个假设上）。

2.3 分支策略：按团队规模选型

分支策略没有唯一正解，选型看两个变量：团队并行度与发布节奏。小团队直接主干开发加短生命周期特性分支，合并前过评审与检查；多版本并行维护或固定发布窗口的团队用主干加版本分支的模式；并行度极高的开源项目常用特性分支加严格评审的守门模式。共同原则：特性分支生命周期要短（活太久的分支合并冲突指数增长）、主干永远可用（保护规则加检查门禁）、合并前过评审（第 6 章把规范检查焊进这个环节）。

提交历史的两种命运

三、工程实践要点

3.1 用提交历史排查回归

规范历史的最直接红利是二分定位：怀疑某回归由近期提交引入时，按提交逐档检出版本运行验证，每次排除一半嫌疑。这个技巧的前提就是本节的两条规范——粒度够细（切一刀有意义）、每个提交可用（任何一档都能跑测试）。团队值得演练一次"两天前的版本有没有这个缺陷"的回溯，体验规范历史与含混历史的效率差。

3.2 提交前的自查

三条自查问题 costing 十秒钟：信息能让人不看差异就明白"为什么改"吗；这个提交混了不相关的东西吗；此刻检出到这个提交，测试全绿吗。三问通过再提交。配合第 6 章的提交钩子（提交前自动跑格式与检查），自查主要剩"动机写清了吗"这一项。

⚠️ 常见坑：把"提交"当成"保存"。有人每五分钟提交一次存进度，历史里堆满"存档""再存一次"式的碎片，最后再靠一个巨型合并把它们焊死——这等于把无规范历史的生成过程自动化了。正确做法：本地用暂存机制灵活组织改动，达到"一个逻辑变更完成"的状态才形成正式提交；进度保存交给编辑器与本地分支。

💡 关键直觉：写提交信息时的假想读者是"六个月后排查相关问题的自己或同事"。一行信息回答"改了什么"，必要时正文回答"为什么"——这两个问题的答案在差异里找不到，只存在于提交信息里。

本章回顾

• 历史是事件日志：含混的历史等于加密存储，密钥随作者遗忘而丢失
• 约定式提交：类型加对象加动机，给人可扫读、给机器可解析
• 小步提交：一提交一逻辑变更、单独可回滚、检出即可用
• 三种污染：功能混格式化、多特性混提、半成品提交
• 分支选型看并行度：特性分支短命、主干永远可用、合并必过检查
• 二分定位红利：规范粒度让回归回溯从通灵变成折半搜索

下一章进入实战收官：把这些规范配置成格式化工具、静态检查与流水线，让机器替团队守规矩。