7.4 版本控制与文档管理

7.4 版本控制与文档管理

本节摘要：版本管理回答"现在跑的是哪一版、和谁不一样、谁改的为什么改"；文档管理回答"三个月后的人能否复原当初的思路"。本节给出青线的分支模型、变更单制度与文档同源纪律——现场在线修改是版本管理的头号敌人，制度必须长在它必经的路上。

先讲一个反面开场。同行为什么深夜被叫到现场？产线异常，怀疑程序被改过。打开工程一看：本地工程、笔记本备份、控制器在线版本三个互相不一致，谁也说不清线上跑的是哪一版、两处差异是哪天谁为了什么改的。最后靠比对工具逐块排查两小时，找到了一行"顺手改"的过滤器参数——问题解决了，但那种"无人知晓程序经历了什么"的恐惧，每个自动化工程师都不该再经历第二次。本节的全部内容，就是把这种恐惧变成不可能。

半夜被叫的那个项目：教训的制度化

那个项目的问题不在技术，在没有制度。青线的版本制度从三个痛点反向设计。痛点一：工程文件是二进制的，版本管理工具对它做不了有意义的差异比对——解法是双轨制：工程文件整体入库当"快照"，同时用平台的源码导出功能把程序块、变量表导出为文本入库当"可读差异"，快照保证能复原，文本保证能审阅。痛点二：在线修改绕过版本库——解法是让在线修改必须过变更单这道闸，比对工具每周例行核查（6.4节的照妖镜制度化）。痛点三：文档与程序脱节——解法是同源纪律：文档版本号与程序版本号绑定变更，改程序必问"哪份文档要跟着动"。

分支模型：产线项目的轻量版

软件团队的复杂分支流搬上产线会水土不服，青线用了轻量三件套。主分支对应现场生产版本，永远可交付；功能分支接新需求，改完经仿真回归与评审合入；热修复分支接现场紧急问题，允许最小修改快速合入，但变更单事后二十四小时内必须补全。三个月一次版本打包，程序快照、文本导出、对应文档、用例库一起归档——7.3节移交包的格式就是它的首版。

热修复分支最考验纪律：现场产线停着，人人都有"先改了再说"的冲动。青线给冲动留了一个合法出口：热修复允许先改，但改前必须从主分支拉出、改后必须立即记录"改了哪个块、哪个参数、为什么"——三项记录加仿真回归，补全手续其实只要二十分钟，比"日后说不清"便宜太多。

变更单：让每个差异都有户口

变更单是版本制度的心脏，字段少而精：变更编号、提出人与日期、影响分析（改哪些块、波及哪些联锁）、回归用例清单、实施窗口、回退方案、双签。青线一年累计开出六十一张变更单，回看最有价值的不是流程本身，而是影响分析一栏养成的习惯——每次改动前先回答"它会波及谁"，4.5节重构后的分层结构让这个问题答得又快又准。

同源：文档是程序的另一半

文档管理的核心纪律是同源：每份文档登记它对应的程序版本，程序变更的评审清单里固定一问"哪份文档跟着改"。听起来繁琐，实际成本极低——多数变更只动一两份文档，而收益在6.4节的排查里立即兑现：诊断缓冲给出报警号，字典一查有语义，规格书一翻有行为定义，维护者三分钟建立全貌。青线交付后的首次大修，新接手的工程师按移交包独立完成，没有打过一次电话问原作者——这就是同源的验收标准。

给读者的起步建议：不必一步到位上全流程，先做两件事——把工程文件加文本导出每周入一次库，给每次修改写三行变更记录。这两件小事坚持一个季度，你就会离不开它；制度的进化由需求牵引，不在起点求全。

版本号与发布节奏：让"哪一版"三个字有答案

版本管理的日常载体是编号规则。青线的版本号三段式：主版本.功能版本.修订号——安全与联锁变更升主版本（需重新验证相关证据链）、一般功能变更升功能版本、参数与文本修订升修订号。规则本身简单，价值在配套的纪律：HMI上常显当前版本号，现场任何人一眼能答"跑的哪一版"；7.3节的交接班比对、6.4节的照妖镜检查，都以它为对账基准。发布节奏固定每月一个功能版本窗口，紧急修订走热修复不受窗口限制但二十四小时内补全手续——固定节奏让"什么时候能上变更"有预期，预期本身就是变更秩序的一半。

给团队起步的最后一个建议：把"版本号三问"贴在工程室墙上——现在跑的是哪一版、和库里哪一版差在哪、下一个版本什么时候上。三问都有秒答的团队，版本管理就及格了；答不出的团队，先别谈分支策略，先把三问问出答案。

本节要点回顾

• 双轨入库：二进制快照保复原、文本导出保可读，两者缺一不可；
• 轻量三件套：主分支、功能分支、热修复分支，热修复先改后补手续但三项记录不可省；
• 变更单心脏：影响分析养成的"波及思维"比流程纸面更有价值；
• 同源纪律：文档登记程序版本、变更必问文档，排查时三分钟建立全貌。

流程四关走完，青线正式交付。下一章看签字之后的长跑：这张网与IT世界如何融合，产线走向何处。