文档的维护责任绑定到组件的变更流程
别名: 文档随变更走 · 文档所有权 · docs in the PR · documentation ownership
概念解释
组件的公开接口一变，现场说明、可运行示例和长文必须在同一次变更里改完，并且有一个具名的人在评审里为「说明仍与接口同一版本」签字。绑定到变更流程（docs bound to the change flow）说的是责任挂在那张变更单上，不是挂在「文档小组稍后会跟」。接口先合、说明后补，现场永远落后一拍；落后的那一拍里，使用方读到的是上一版的用法。
责任不是「有人写过文档」。写过只证明历史上存在过一份。绑定要求：改属性的人同时改旁注，删入口的人同时删示例，评审清单上有一项过不了就不能合。所有权跟组件走，不跟写作兴趣走。
机制
文档和代码若走两条队列，代码队列更快——测试红了会挡住发布，文档黄了没有同等的门。于是说明成为自愿劳动，排期一紧就被拿掉。变更单把两份产物收成一个原子：要么接口与说明一起进入主线，要么一起留下。原子性把「谁来写」从道德问题收成流程问题：没改说明的变更单不完整，跟没改测试一样。
所有权若不具名，流程门会变成无人认领的检查项，最后被跳过。具名到组件维护者（或明确的代理），签字的人就是下次被问「现场为什么还在教旧属性」时要回答的人。责任与变更绑在一起，是因为只有变更发生的那一刻，作者才同时看见旧接口和新接口；事后补写的人看不见当时为什么删，只能猜。
边界
尚未公开的探索分支不必为每次试验改长文；绑定从接口声明为稳定、准备进入主线时开始。安全应急热修若只动内部实现、公开用法不变，允许文档项空过，但要在变更单上写明「公开接口未变」并被复核。翻译滞后可以另排，源语言的现场旁注不行——使用方读的是源旁注。把文档全部外包给从不改代码的小组，绑定会在交接处断裂，除非该小组作为维护者写进同一张变更单的评审人列表。
怎么落地
- 变更清单设硬项：公开属性、插槽、默认值有改动时，必须同时改类型旁注、可运行示例和版本化长文链接；缺一项不能合。
- 每个组件在元数据里写维护者；文档评审人默认是维护者，不是「谁有空」。
- 删除或改名的接口，在同一变更里把现场仍能搜到的旧句子删掉或标为失效，避免旧说明作为活入口留下。
- 验证：抽最近十次改了公开接口的变更单，数有多少张在同一提交里改了旁注和示例。零改动的那些，去现场悬停读一句：若仍在教旧名字，绑定失败。再故意提一张只改接口、不改说明的变更，看门禁是否拦住——拦不住就还是自愿劳动。