写一份让读者看懂改了什么、该做什么的更新日志

## 弄清谁会读更新日志，以及哪些变更与他们有关 更新日志应面向受软件变更影响的人编写，而不是作为由机器验证的规范或开发活动的原始堆砌。每一项编辑选择都应帮助读者更轻松地理解该版本。 起草前，请明确： - 所描述的发布或版本。 - 依赖该产品、库、服务或文档的人群。 - 会改变行为、预期、兼容性、无障碍性、安全性或所需行动的变更。 - 项目已经采用的版本编号、标题和条目惯例。 把惯例当作工具，而不是判断的替代品。当现有结构有助于读者比较不同版本时，应予以保留；但不要仅仅为了符合某个标签，就将变更强行表述成误导性的措辞。当某条规则必须严格执行时，应解释原因，使贡献者能够明智地应用它。 将更新日志原则与设置说明及常规贡献流程分开。为每类指导保留一个权威位置，并通过链接指向它，而不是重复可能逐渐产生偏差的说明。 ## 只写与读者有关的变更，并说明为什么重要 从读者的角度审查候选变更。当某项变更会改变一个人能够做什么、观察到什么、依赖什么、配置什么、迁移什么或保护什么时，应将其纳入。若内部活动没有实质影响，则应排除；除非它能解释相关的运维或兼容性后果。 对于每项纳入的变更，请回答： 1. 从可观察的角度看，发生了什么变化？ 2. 谁会受到影响，又是在什么条件下受到影响？ 3. 这项变更为何重要？ 4. 读者是否需要采取行动？如果需要，必须采取什么行动？ 先说明结果。只添加避免误解所必需的背景。明确说明条件、例外和迁移影响；不要把它们隐藏在含糊的摘要背后。 不要仅仅因为某个工具很流行就推广它，也不要凭空设计一个并未解决任何已证实沟通问题的流程。除非当前做法妨碍读者理解重要变更，否则应优先采用简单的条目和项目现有的工作流程。 指南和建议应包含其理由。读者应能在了解权衡和预期收益的基础上，有理有据地提出不同意见。 ## 用平实的语言写出每项变更的影响和需要做的事 使用浅白语言，并先说重点。避免设置理解门槛、使用圈内缩写、堆砌华而不实的复杂性，以及写出迫使读者自行重构核心观点的句子。措辞应让非母语读者第一次阅读就能理解，也应让译者能够直接翻译，而不是重新诠释。 将以下要素清楚地区分开： - 变更本身：对之前行为和新行为的具体描述。 - 影响：受影响的用户、环境、版本或工作流程。 - 原因：所解决的问题或所维护的原则。 - 行动：读者必须采取的任何升级、配置、迁移或验证步骤。 不要夸大确定性或影响。如果行为会因情境而异，应明确说明条件，而不是发布普遍适用的命令。如果读者无需采取行动，就不要凭空制造行动要求。 在不同条目和版本中一致地使用术语。首次使用不可避免的专业术语时应加以解释，保留重要区别，并避免使用会弱化警告或破坏性变更信息的委婉说法。 对相关文档、贡献说明和提交消息也采用同样清晰、重点优先的风格，使变更记录获得一致的源信息支持。 ## 检查译文与原文意思一致，最后由人来定稿 将翻译视为一等的变更沟通内容。针对特定版本的翻译必须已经存在，或者提供清晰的贡献指引。它必须与规范源保持准确一致，同时也应在自身语言和文化语境中易于理解。 页面结构、版本路由和源标记应足够简单，使不具备编程背景的译者也能编辑。在更改标题、标识符、版本关系或标记惯例之前，应评估该变更对所有受维护语言和版本的影响。 请采用以下审查顺序： 1. 在翻译之前，先确定规范条目的最终含义。 2. 记录哪些版本和语言需要此项变更。 3. 检查每项必需翻译是否存在，或是否有清晰的贡献途径。 4. 将译文含义与规范源比较，检查是否存在遗漏、含义反转、条件改变和术语不一致。 5. 由了解该语言和文化的人作出最终编辑决定。 不要用机器生成的文本代替译者。自动化或模型辅助检查可以找出覆盖缺失和可能的不一致，但含义、文化适切性和最终措辞由人负责。 ## 重复的检查交给简单的工具，判断留给人 使用自动化减少跨语言、跨版本和跨展示环境的重复验证。合适的对象包括翻译覆盖检查、版本路由测试、语义比较辅助工具、无障碍检查，以及视觉或功能回归测试。 优先选择创建后无需模型、可在本地或离线运行的常规可复用工具。语言模型可以帮助一次性设计或实现工具，但由此产生的检查应可供审查、可重复执行、运行成本低廉，并能独立运行。 模型不得： - 取代人工译者或文化审查。 - 决定项目的编辑立场或其指导内容的含义。 - 为没有独立需求的功能或流程辩护。 由人来判断更新日志条目是否准确、有用且恰当。工具提供证据，但不拥有结论的决定权。 保持发布系统简单且持久。优先使用现有的构建和创作工具链；只有在当前方法无法安全满足某项具体要求时，才添加依赖项、服务、数据库或新的运行时。仅用于开发阶段的验证工具不得成为不必要的生产要求。 发布前，请确认规范条目清晰，所需版本和翻译均已覆盖，自动化检查取得了实际结果，并且最终含义已由人工审查。