第4章 代码管理那些事儿
从源码由个人目录和口头约定管理走到每个变更具来源、验证和可恢复产物，沿提交、构建、测试与回退边界诊断代码管理。
学习目标
- 能沿建立变更、提交历史、解析构建、自动验证和发布回退追踪一条可审查代码流水线
- 能解释变更身份、构建依赖、测试证据、发布产物和回退点如何共同支撑可恢复交付
- 能在正常、边界和故障场景中回答：一次提交混入无关重构与功能时，哪一条证据让回退和定位失去独立性
为什么需要这一机制
本页依据刘欣《码农翻身》（2018 年第 1 版）及出版社公开书目信息，独立重构 第4章 代码管理那些事儿。正文、代码、图示、实验和练习都是本课程重新设计的教学材料，不复制原书正文、插图、练习答案或代码。
第4章 代码管理那些事儿 不能停在“把文件放到某个仓库”。真实系统要解决的变化是从 源码由个人目录和口头约定管理 到 每个变更具来源、验证和可恢复产物；可执行机制是：代码管理把变更身份、构建依赖、自动测试、缺陷证据和发布产物连成可审查流水线。
三个会让代码管理失真的陷阱
一个目录节点到代码管理证据
第4章 代码管理那些事儿
在 ↡把代码变更的身份、历史、构建、验证、发布和回退连接成可审查、可恢复流水线的工程机制。 中，验收合同可写成
每个箭头都要留下证据：谁改变了什么、由哪个提交代表、用什么依赖构建、哪些测试通过、发布了哪个不可变产物，以及失败时回到哪里。代码管理不是文件备份，而是把变更和结果绑定。
建立变更
↡从一个明确意图开始，列出改动范围、风险、验证方式和预期差异的阶段。先固定问题和最小修改集。工作区应能说明未提交内容、相关测试和预期结果；无关改动必须被发现并拆开。
提交历史
↡用带作者、时间、父提交和意图说明的不可变记录表达一次可审查变更的历史。让定位和回退有坐标。提交应小而完整，信息说明原因、影响和验证；合并前要确认父提交和冲突解决没有吞掉重要变化。
解析构建
↡解析锁定的依赖、配置和工具链，将源码转换成可标识、可复现构建产物的阶段。不是“本机能编译”而已。保存工具链、依赖锁、环境、构建日志和产物摘要，避免不同机器生成无法比较的结果。
自动验证
↡用自动测试、静态检查和针对变更的证据验证提交满足合同并记录失败原因的阶段。要覆盖行为、结构和风险。测试通过也不代表所有风险消失，但没有可重放报告就不能把绿色状态作为发布依据。
发布回退
↡将经过验证的不可变产物发布到目标环境，并在失败时按已记录版本和步骤恢复的阶段。把可恢复性纳入交付。回退不仅是换二进制，还要检查配置、迁移、数据兼容、流量和验证结果。
最小可重放实现
change = prepare("one-intent")
commit = record(change, message, author)
artifact = build(commit, locked_dependencies)
report = verify(artifact, test_plan)
assert release(artifact, report).rollback_target == commit这段实现草图只表达代码管理合同，不复制原书叙事或代码。实际运行时应保存工作区差异、提交、依赖、构建日志、测试报告、产物摘要、发布环境和回退目标，使另一位读者能够从干净状态重放。
五步复核一次代码交付
1. 建立单一意图的变更
记录目标、影响范围、风险、预期差异和验证计划。先预测正常提交会改变哪些文件与行为，再检查工作区是否混入无关重构。
Lab
代码交付与回退实验
先预测一个提交会生成什么证据，再切换混合变更与发布故障并验证回退轨迹。
单一意图提交通过验证，产物和回退目标已绑定
commit=c-01 → build=artifact-a → tests=pass → release=r-01 → rollback=c-01
判定
accept：来源、验证和恢复证据闭环
当前样本：可恢复发布；保存提交、依赖锁、构建日志、测试报告、产物摘要、发布版本和回退轨迹。
正常、边界与故障证据矩阵
| 样本 | 只改变的变量 | 预期判定 | 必存证据 |
|---|---|---|---|
| 正常 | 单一意图、依赖锁、测试和产物均匹配 | 可审查发布并指向回退目标 | 提交、构建、报告、产物、环境 |
| 边界 | 合并冲突、依赖变化或配置差异 | 明确审查或暂停发布 | 父提交、锁文件、差异、策略 |
| 故障 | 测试失败、运行缺陷或产物不一致 | 定位首错并回到已验证版本 | 报告、日志、产物摘要、回退轨迹 |
故障诊断：先分开变更、构建与发布证据
- 变更侧：查工作区差异、意图、影响范围和无关文件；混合提交会让所有后续定位变难。
- 历史侧：查作者、父提交、合并冲突和提交说明；先确定哪一个提交引入了行为变化。
- 构建侧：查工具链、依赖锁、环境、构建日志和产物摘要；本机通过不等于产物可复现。
- 发布侧：查测试报告、配置、迁移、目标版本和回退步骤；回退二进制不代表数据状态已恢复。
如果测试失败，先按提交差异定位再看环境；如果构建结果不同，比较依赖锁和工具链；如果发布后故障，绑定请求、产物、配置和回退目标。每次只改变一个变量，并重放可信基线。
术语表
名词解释
本章出现的专业名词，用大白话再讲一遍。
- 第4章 代码管理那些事儿
把变更身份、历史、构建、验证、发布和回退连接成可审查流水线的工程机制。
- 建立变更
从明确意图开始列出改动范围、风险、验证方式和预期差异的阶段。
- 提交历史
用作者、父提交和意图说明表达一次可审查变更的不可变记录。
- 解析构建
解析锁定依赖和工具链，将源码转成可标识、可复现产物的阶段。
- 自动验证
用测试、静态检查和变更证据验证提交并记录失败原因的阶段。
- 发布回退
发布经验证产物，并在失败时按版本、配置和步骤恢复的阶段。
练习
练习
问题 1（第4章 代码管理那些事儿）： 为什么代码管理的合同必须把提交、构建、测试和发布产物连起来，而不只是保存源码？
问题 2（建立变更、提交历史、解析构建）： 一次提交混入格式化、重构和功能时，如何拆出可回退历史？
问题 3（自动验证、发布回退）： 发布后发现缺陷，哪些证据决定回退是否安全？
本页小结
第4章 代码管理那些事儿 的关键不是存一份源码，而是让每个变更都拥有来源、可复现构建、自动验证、不可变产物和可演练回退。完成标准是定位混合提交或发布故障的首个偏离，并证明复位后同一输入能回到已验证基线。