docs: 决策记录 8 条、变更日志、README 的验收与口令两节

0007 与 0008 是本次改造新产生的决策(原计划 6 条)。它们同样满足「后人会问为什么」:把运行锁改成互斥体、或给库里 27 个函数补上 SupportsShouldProcess,都是看起来更规范的错法。

CHANGELOG.md:把 README 里那 33 行「相对旧版修了什么」整节搬过去,并补上本次改造的记录(11 条修复 + 6 条结构与规范,每条修复都写明现象与现状)。README 那一节换成指针。

README 新增两节:「验收与静态分析」(六个层次、Run-RealSmoke 为什么独立存在、以及那 6 条格式规则默认 Disabled 这个容易漏掉的事实);「口令放在哪里」(默认留空不是遗漏,附迁移与验证命令)。

.markdownlint.json 照 PowerShell 主仓库的实践(default true、行长 240),只把 MD024 从关闭改成「仅同级不重复」,因为变更日志需要重复标题。顺带按 .editorconfig 把 .md 的 BOM 去掉。
This commit is contained in:
Shuery committed 2026-09-27 10:01:54 +08:00
1 parent 42f02d0eca
commit 3a3a57a6a1
12 files changed
+282 -33

No files matched your search

+20
View File
@@ -0,0 +1,20 @@
# 静态分析的三条有意排除,以及 160 字符的行长
`PSScriptAnalyzerSettings.psd1` 里用 `Rules` 把 6 条格式规则显式打开(它们默认全是
Disabled —— 不带 `-Settings` 的 `Invoke-ScriptAnalyzer -Severity Warning,Error`
**一个排版问题都不会报**),同时有意排除三条:
- **`PSAvoidUsingWriteHost`** —— `Write-Log` 的彩色控制台输出是这份工具的刻意设计,不是疏忽。
这是架构性选择,所以在配置里排除,而不是逐处 `Suppress` 假装它是例外。
- **`PSUseShouldProcessForStateChangingFunctions`** —— 报 27 个改状态的函数。给它们都加上
`SupportsShouldProcess` 会更糟:`WhatIf` 的边界在 `Backup.ps1` / `Restore.ps1`(它们自己管
`-DryRun` / `-WhatIf`),如果库里 27 个函数也各自实现一遍,那么入口把 `$WhatIfPreference`
置真之后,它们会**静默跳过自己的工作** —— 备份看起来成功却什么都没做。这是一个"听着更规范、
实际更危险"的典型。
- **`PSAvoidUsingPlainTextForPassword`** —— 7z 只接受命令行口令(7z 自身的限制)。口令在这个
工具里必然是明文字符串,规则说的"用 `SecureString`"在这里没有落点。真正要守的两条另有措施:
口令不进日志(遮蔽 + 断言)、口令不进版本库(`.gitignore` + 出厂默认值留空)。
**行长上限设成 160,而不是官方默认的 120。** 120 在这个仓库意味着 270 处改动(主要是中文
注释与测试夹具里的一行式目录),160 意味着 41 处,而 41 处当时没做完。这是一次有意的偏离:
数字写在配置文件的注释里而不是悄悄放宽,想收紧到 120 时那份清单就在分析器的输出里。