Back to Details

writing-changelogs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing changelogs

编写变更日志

REQUIRED BACKGROUND: the 
technical-writing
skill (hard rules, truth rules, style).
必填背景： 
technical-writing
技能（硬性规则、真实规则、风格）。

Overview

概述

The changelog is the one place where describing the change, not the current state, is the job. It is historical: entries are never rewritten, only appended.
变更日志的核心任务是描述变更，而非当前状态。它属于历史记录：条目永远只能追加，不得改写。

When to invoke, and not

使用场景与禁用场景

Invoke after shipping a meaningful change (a feature, a fix of real size, a removal), when writing release notes, or when summarizing what shipped. Do NOT invoke for trivial edits (a threshold of roughly three changed files or commits keeps the log meaningful), and never rewrite or delete existing entries: the changelog is historical by classification.
在交付重要变更（功能、规模较大的修复、移除操作）后、编写发布说明或总结已交付内容时可使用。请勿用于无关紧要的编辑（大致以修改3个文件或提交为阈值，以确保日志的实用性），且绝不能改写或删除现有条目：变更日志本质上是历史记录。

Rules

规则

  • One entry per shipped change, newest first, ISO dates, grouped by version where versions exist. Strict, not marketing.
  • Standard categories where the file uses them: Added / Changed / Deprecated / Fixed / Removed / Security. A Deprecated entry carries the removal date and the replacement.
  • Breaking changes lead the entry, above the categories, each with the required migration action stated (and the migration guide linked when one exists). A breaking change buried under Added is the entry the reader needed most and found last.
  • User-visible impact over implementation detail; present tense, active voice; no jargon the reader would not know; group related changes; never duplicate an existing entry.
  • Record removals, not just additions: readers chase dead concepts otherwise.
  • Release notes are the audience-facing cut of the same facts: what changed, who it affects, what to do about it. The changelog speaks to engineers; release notes to users of the system. Same sources, different register, never contradicting each other.
  • 每个已交付变更对应一条条目，最新条目在前，使用ISO日期；若有版本，则按版本分组。表述严谨，避免营销化语言。
  • 若文件使用标准分类，则遵循：新增（Added）/ 变更（Changed）/ 弃用（Deprecated）/ 修复（Fixed）/ 移除（Removed）/ 安全（Security）。弃用条目需注明移除日期及替代方案。
  • 破坏性变更需置于条目最上方，在分类之前，每条都需说明必要的迁移操作（若有迁移指南则需附带链接）。将破坏性变更隐藏在“新增”分类下，会让读者最需要的信息最后才被找到。
  • 优先描述用户可见的影响，而非实现细节；使用现在时、主动语态；避免读者不懂的行话；将相关变更分组；切勿重复现有条目。
  • 记录移除操作，而非仅记录新增：否则读者会被已废弃的概念误导。
  • 发布说明是面向受众的事实提炼：包括变更内容、影响人群、应对措施。变更日志面向工程师，发布说明面向系统用户。两者来源相同，但表述风格不同，且绝不能相互矛盾。

Entry shape

条目格式

Document-type exception: the bold leads required below override the shared ban on bold-lead bullets. The exception covers changelog outcomes and the named known-issue, deferred-item, and omission categories only. Repeated label-value bullets remain banned elsewhere.
Bold lead stating the outcome, then root cause, then the fix, with exact names inline:
markdown
- **Reference-to-video routing fixed.** The resolver only knew three operation
  kinds, so requests with reference media routed to image-to-video. A
  `hasReferenceMedia()` check now gives reference-to-video a higher-priority
  branch.
Fixed entries explain the failure mode, not the diff. A "why it matters" clause turns a change list into something a reader can triage.
文档类型例外： 下文要求的粗体开头内容，不受通用规则中“禁止粗体开头项目符号”的限制。该例外仅适用于变更日志结果，以及明确标注的已知问题、延迟事项和遗漏分类。其他场景仍禁止重复使用标签-值形式的项目符号。
以粗体开头说明结果，然后说明根本原因，再描述修复方案，同时在文中使用准确名称：
markdown
- **Reference-to-video routing fixed.** The resolver only knew three operation
  kinds, so requests with reference media routed to image-to-video. A
  `hasReferenceMedia()` check now gives reference-to-video a higher-priority
  branch.
修复条目需说明故障模式，而非代码差异。添加“为何重要”的说明，能让变更列表变成读者可筛选的实用内容。

Honesty conventions

如实记录准则

The entries almost nobody writes, and the reason a changelog becomes citable:
  • Known issues surfaced but not fixed in this change, named as such.
  • Deferred items still owed ("one deploy needed to restore the webhook key").
  • Deliberate omissions, described by category, so the same omission is not re-litigated or mistaken for an oversight.
Never mark anything shipped, deployed, or verified unless that exact action was completed and checked. Distinguish implemented (in the repo) from deployed (live) from externally verified.
这些条目几乎没人会写，但却是变更日志具备可信度的关键：
  • 已知问题：本次变更中发现但未修复的问题，需明确标注。
  • 延迟事项：仍未完成的工作（如“需再部署一次以恢复Webhook密钥”）。
  • 故意遗漏：按分类说明，避免同一遗漏被反复讨论或被误认为疏忽。
除非确实完成并验证了相关操作，否则绝不能标记任何内容为已交付、已部署或已验证。需区分已实现（在代码库中）、已部署（已上线）和已外部验证三种状态。

Handover / completion summary

交接/完成摘要

For handing finished work to a reviewer or operator, the sections most handovers lack and readers most need:
  1. Why this work exists
  2. What shipped
  3. Where to point the review (the decisions a reviewer must understand before judging)
  4. Verification status: exact commands and their results, never a bare checkmark
  5. Honest caveats and things I got wrong
  6. Residual risks and what NOT to do
  7. State and what is owed (merged-not-pushed, migrations, ordered steps with the consequence of wrong ordering)
Naming a section for self-reported error makes it socially safe to write.
在向审核者或运维人员移交已完成工作时，以下是大多数交接内容缺失但读者最需要的部分：
  1. 这项工作的存在原因
  2. 已交付的内容
  3. 审核重点（审核者在评判前必须理解的决策）
  4. 验证状态：准确的命令及其结果，绝不能仅用一个勾选标记
  5. 如实说明的注意事项和自己犯的错误
  6. 剩余风险及禁止操作
  7. 当前状态及未完成事项（已合并但未推送、迁移操作、有顺序要求的步骤及顺序错误的后果）
设置一个“自我报告错误”的部分，能让作者更放心地如实记录。