docs(dev-tooling): 补三条 —— 布局改动的回滚账、PIPESTATUS 与 pipefail 是判据的一部分、判据输出要自证比完全部对象

第 10 条是 pi 提的:把 lib/user-question.js 搬到 test/lib/ 的收益是'快照更干净',
但**回滚它会让快照立刻多出一处运行时漂移** —— 这类改动的账里没有'回滚'这一行。
第 11 条把管道纪律写清取法,并点明四个 deploy 脚本的 set -o pipefail 不是风格而是判据。
第 12 条来自实测:show_diff 的 cmp|head 在 set -e 下让脚本当场中止,
只报第一个对象、退出码却恰好还是 1 —— 判定对、证据被截断。
This commit is contained in:
2026-09-14 20:35:10 +08:00
parent 42f01c7478
commit d47035aaff

View File

@ -184,7 +184,24 @@ bash deploy/prune-deploy-artifacts.sh --self-check # 判据自检(16 项,
9. **变异之前先提交。** 我在**未提交**状态下变异,然后用 `git checkout HEAD -- <file>`
还原,把自己的改动一起冲掉了(这条纪律我写过、还是踩了)。
顺序必须是:提交 → 变异 → 确认红 → `cp` 还原 → `cmp` 校验。
10. **注释里的数字无法被判据守住。** 同一文件里曾同时写"写点五处"和"共 6 处"
10. **改"布局/文件集"时,先在脑子里跑一遍"如果这一步被回滚,部署判据会怎么变"。**
(pi 2026-09-14 提的,很准。)实例:把 `lib/user-question.js` 搬到 `test/lib/`,
收益是"快照更干净";但**回滚它会让快照立刻多出一处运行时漂移** ——
因为快照是"搬家后"的树,而仓库回到了"搬家前"。这类改动的收益账里没有这一项,
于是它不体现在任何判据里,只体现在回滚之后的红灯上。
11. **判据的退出码不许经管道取值**(与第 6 条同源,写清取法):临时命令里
`cmd | tail -25; echo $?` 拿到的是 `tail` 的退出码。**要取就读 `${PIPESTATUS[0]}`**。
脚本侧四个 deploy 脚本都有 `set -o pipefail`(`install.sh` 还带 `-e`),
所以脚本内的管道判定是对的 —— **但那是判据的一部分,不是风格**:
`redeploy-plugin.sh` 的 `if ! node … | sed …; then` 与 `install.sh` 里同形状那处,
依赖 `pipefail` 才测的是被检程序的状态;谁重构时把 `set -o pipefail` 删了或挪了位置,
判定会静默变成"`sed` 成功即成功"。**动那几行要连着 pipefail 一起想。**
12. **判据的输出必须能自证"它比完了全部对象"。** 实例:`check-shared-libs.sh` 的
`show_diff` 里 `cmp … | head -3` 在 `set -euo pipefail` 下返回 1 ⇒ 独立调用触发
`set -e` ⇒ **脚本当场中止**:只报第一个分叉文件,后续对象与收尾汇总都不打印。
退出码**恰好还是 1**(判定是对的),所以光量退出码看不见它 ——
这正是"判定对、证据被截断"。修法 `|| true`,并在注释里写明它不是风格而是判据。
13. **注释里的数字无法被判据守住。** 同一文件里曾同时写"写点五处"和"共 6 处"
(且它的式子 2+2+3 加起来是 7,实际 10 处)——**三处说法三个数**。
与"不要手抄期望用例数常量"同源:**两组矛盾的数字比没有数字更糟**,
因为它让读者以为有人数过。要判覆盖完整只能靠**机制**(整段 try/catch),不靠数数。