Skip to content

docs: 更新文案改成浅显写法 - #6

Merged
mingyangbest merged 1 commit into
mainfrom
docs/plain-release-notes
Nov 2, 2026
Merged

mingyangbest merged 1 commit into
mainfrom
docs/plain-release-notes

Conversation

@mingyangbest

Copy link
Copy Markdown
Owner

只改一个文件:CHANGELOG.md。不动代码、不动配置、不影响部署。

改了什么

原来的写法是每条一个粗体小标题、后面跟一长串分号从句,还夹着 strptime、age_days、stale、check.sh 这种用户看不懂的实现细节。改成一条一件事、说清「会出现什么现象」,实现细节要么删要么换成白话。

两处对照:

原:演练哈希抽查:体积比对通过后再比 SHA256;不一致判失败,云端无哈希时不推翻体积结论;上报失败不影响演练退出码。

新:演练加查内容:以前只比文件大小,现在大小对了还要比 SHA256,内容不一致算失败。云端没返回哈希时,以大小为准,不会误判。

原:strptime(at, "%F %T") 里的 %F 不被 strptime 支持,异常被吞掉导致 age_days 恒为 None、stale 恒为 False。

新:判断时间时用错了格式,报错又被吞掉,结果永远是「没过期」。

顺手修了一处不实表述

v0.2.0 的「说明」里写过「孤儿扫描的排除规则与同步一致」,当时并不成立——同步只排目录、文件没排(就是 v0.2.1 修的第二条)。这句从 v0.2.0 段落删掉,v0.2.1 里注明「从本版起才成立」。

与 Releases 页的关系

v0.2.0 段落与线上 Release 正文逐字一致(只差标题层级 ## / ###),因为 Releases 页的 v0.2.0 已经用同一份文案重写了。以后 v0.2.1 发版直接取这一段。

验证

git diff --stat:1 file changed。没跑任何代码,也就不涉及 CI 的构建结果。

改成「说人话、说影响」的写法:

- 去掉每条开头的粗体小标题和冒号排比,一条一件事,一两句话说清
- 用户看不懂的实现细节(strptime 格式、age_days/stale、check.sh、py_compile)
  要么删掉,要么换成「会出现什么现象」
- 修掉 v0.2.0 里一句不实的说明:「孤儿扫描的排除规则与同步一致」——
  当时同步只排目录、文件没排,这句话到 v0.2.1 才成立
- v0.2.0 段落与 Releases 页保持一致(只差标题层级)
@mingyangbest
mingyangbest merged commit eaa5b2d into main Nov 2, 2026
2 checks passed
@mingyangbest
mingyangbest deleted the docs/plain-release-notes branch November 3, 2026 11:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant