跳到正文

发布记录与变更集

从读者能遇到的变化写发布条目,把版本、影响和操作连接到对应指南。

从影响写第一句

写出变化在什么条件下发生,以及用户会观察到什么。需要操作时交代适用对象和动作,再链接到同版本的详细指南。修复条目可以先写故障触发条件,再写修复后的可观察结果。

原句改写
调整搜索逻辑。查询含空格的标题时,按完整词组排序。
修复缓存问题。切换文档语言后,搜索使用目标语言的索引。
更新配置结构。从 2.0 起,离线索引使用 search.output 指定输出文件。已有配置需要迁移。

把条目放在对应版本

按项目的发布流程给出版本号。如果仓库使用变更集生成发布记录,按该项目定义的格式标记受影响的包和版本级别。翻译上游发布记录时,保留同一版本中的分组、条件和错误码。

发布日期、支持状态和升级边界需要来源。把固定版本的发布记录与对应文档相互链接。涉及多个包时说明哪个版本的组合支持该行为。

区分发布摘要和迁移步骤

发布记录适合提示影响,指南承载完整任务。示例条目可以写成“使用旧输出路径的项目需要按输出配置迁移示例检查构建产物”。再在指南中写准备工作、修改、验证和回退条件。发布后实际打开链接,确认目标版本和锚点都能找到。