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

+18
View File
@@ -0,0 +1,18 @@
# 同时支持 Windows PowerShell 5.1 与 PowerShell 7.x,源文件一律 UTF-8 with BOM
README 一开始就承诺"只依赖 PowerShell(5.1 或 7.x)",但实测发现**这个承诺是假的**:全部
源文件是无 BOM 的 UTF-8,而 5.1 在没有 BOM 时按 ANSI 代码页解码源码 —— 中文变乱码,全角
问号之类的字节序列吃掉字符串引号,**6/6 个文件在 5.1 上连语法都过不去**。
决定继续兑现这个承诺,因为计划任务默认可能就用 `powershell.exe` 启动。具体约定:
- 含非 ASCII 的源文件一律 **UTF-8 with BOM**(.editorconfig 里钉死 `charset = utf-8-bom`),
这是同时满足 5.1 与 7 的唯一编码;
- 版本声明写 `#Requires -Version 5.1`,**绝不**写 `#Requires -PSEdition`(两个值互斥,
写哪个都会把另一半环境排除掉);清单里用 `CompatiblePSEditions = @('Desktop','Core')`;
- 不用 `??` / 三元 / `Join-String` / `-AsHashtable` / 三参数 `File.Move`(它是 .NET Core 3.0+
才有的重载,我们改为 `File.Replace`,那个在 .NET Framework 上同样可用);
- 验收门槛在**两个版本上都跑**,而不是只在 7 上跑完宣称兼容。
代价:`#Requires -Version 5.1` 意味着放弃 PS 4.0 及以下;BOM 让某些 Unix 工具不喜欢这些文件。
两者都是刻意的。