Back to Details

writing-release-notes

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing Release Notes

撰写发布说明

Overview

概述

Summarize shipped changes in a way that is accurate, scannable, and appropriate for the intended audience (internal, customers, or both).
以准确、易读且符合目标受众（内部人员、客户或两者兼顾）的方式总结已发布的变更。

When to Use

使用场景

  • A set of PRs/issues is ready for release and needs a coherent summary
  • Stakeholders need to know impact, risk, and required follow-ups
  • You must communicate changes without leaking sensitive/internal details
When NOT to use
  • No user-visible or operationally relevant changes occurred
  • 当一组PRs/议题准备好发布，且需要一份连贯的总结时
  • 干系人需要了解变更的影响、风险以及后续必要操作时
  • 你必须在不泄露敏感/内部细节的前提下沟通变更时
不适用于以下场景
  • 未发生任何用户可见或与运营相关的变更时

Core Pattern

核心原则

Write for outcomes, not implementation:
  • What changed (user-facing)
  • Who is affected (segments, plans, roles)
  • Anything required (migration steps, toggles, downtime)
  • Known issues (if applicable)
围绕成果而非实现细节撰写：
  • 变更内容（面向用户的表述）
  • 影响人群（用户群体、服务套餐、角色）
  • 必要操作（迁移步骤、功能开关、停机时间）
  • 已知问题（如适用）

Quick Reference

快速参考

Use this structure:
  • Highlights (2–5 bullets)
  • Improvements
  • Fixes
  • Breaking changes (if any) + mitigation
  • Operational notes (deploy windows, feature flags) (internal-only)
采用以下结构：
  • 重点亮点（2–5条项目符号）
  • 功能改进
  • 问题修复
  • 破坏性变更（如有）+ 缓解方案
  • 运营说明（部署窗口、功能标志）（仅内部可见）

Implementation

实施步骤

  1. List included tickets/PRs and group by theme.
  2. Rewrite each item as “Outcome + affected area” in plain language.
  3. Add any required actions and clearly label breaking changes.
  4. Remove internal-only details (stack traces, customer names, security-sensitive info).
  1. 列出包含的工单/PRs，并按主题分组。
  2. 将每个条目重写为“成果 + 影响范围”的直白表述。
  3. 添加任何必要操作，并清晰标记破坏性变更。
  4. 删除内部专属细节（堆栈跟踪、客户名称、安全敏感信息）。

Common Mistakes

常见误区

  • Changelog dump: raw PR titles are rarely meaningful—rewrite.
  • Overclaiming: avoid “fixed forever”; be precise about scope.
  • Missing required actions: if users must do something, put it near the top.
  • 直接粘贴变更日志：原始PR标题通常没有实际意义——务必重写。
  • 过度承诺：避免使用“永久修复”这类表述；要精准说明适用范围。
  • 遗漏必要操作：如果用户必须执行某些操作，务必放在显眼位置。