changelog-maintenance

变更日志维护

当交付内容是发布历史或已上线变更的沟通内容，而不是广泛的文档或发布活动套件时，请使用此技能。

changelog-maintenance 是文档集群的核心，适用于：

• 维护 CHANGELOG.md
• GitHub / GitLab / 文档站点的发布说明
• 与已上线变更相关的迁移和弃用更新
• 面向客户的“变更内容”摘要
• 简明的游戏补丁说明和小型更新帖

选择模式或划定范围前，请先阅读以下支持文档：

• references/modes-and-boundaries.md
• references/output-packets-and-channel-handoffs.md
• references/release-note-quality-checklist.md
• references/automation-and-source-of-truth.md

何时使用此技能

• 仓库需要基于已上线工作，补充持久的变更日志条目或刷新 Unreleased
• 发布需要面向开发者、客户、内部利益相关者或玩家的适当说明
• 重大变更、弃用或兼容性调整需要在发布历史中关联迁移更新
• 发布自动化已起草说明，但仍需准确归类、改进措辞或补充更合适的跳转链接
• 游戏更新需要简明的补丁说明，而不是营销文案、部署运行手册或完整帮助文档
• 真正的任务是确定最精简的发布写作交付包，而不是从头编写所有相关文档

何时不使用此技能

• 主要任务是编写内部规格说明、运行手册、ADR、发布计划或深入的迁移流程 → technical-writing
• 主要任务是编写已发布的 API / SDK / webhook / 开发者门户内容 → api-documentation
• 主要任务是编写面向终端用户的入门指南、教程、截图、常见问题或帮助中心操作指南 → technical-writing
• 主要任务是执行部署、环境晋级、回滚机制或发布编排 → deployment-automation
• 主要任务是撰写发布文案、功能定位、活动排期或 GTM 信息 → marketing-automation
• 尚无可信的已上线证据 → 先收集证据，不要根据路线图或待办事项编造发布说明

说明

第 1 步：确定一种主要的发布写作模式

起草前，先规范化请求。

changelog_mode:
  primary_mode: changelog | release-notes | migration-update | game-patch-notes
  audience: developers | end-users | mixed | players | internal-stakeholders | unknown
  release_scope: patch | minor | major | rolling | unknown
  source_of_truth: release-pr | tagged-release | prs | issues | commits | docs | mixed | unknown
  publishing_surface: changelog-file | github-release | docs-site | in-app-updates | steam-news | mixed | unknown
  automation_context: manual | release-drafter | changesets | release-please | autogenerated-release-notes | mixed | unknown
  output_shape: single-entry | summary-plus-links | migration-brief | patch-note-brief | sync-packet | unknown

每次运行只使用一种模式：

• changelog → 在 CHANGELOG.md 中记录持久的仓库历史
• release-notes → 面向受众，概述变更内容及其重要性
• migration-update → 说明行为变更、所需操作、截止日期和兼容性注意事项
• game-patch-notes → 面向玩家的简明更新摘要

第 2 步：确认受众、证据和跳转链接

撰写前回答以下问题：

1. 谁会最先阅读这些内容？
2. 阅读后应采取什么行动？
3. 哪些已上线证据能证明每条核心主张？
4. 其余内容应由哪份更深入的文档承载？

快速跳转表：

如果请求听起来像……	使用
“编写架构 / 发布计划 / 运行手册 / 内部迁移计划”	technical-writing
“发布 API 参考文档、SDK 文档、身份验证故障排查指南或门户页面”	api-documentation
“为变更后的工作流编写帮助文档、教程、截图或常见问题”	technical-writing
“规划部署 / 回滚 / 发布执行”	deployment-automation
“撰写发布文案 / 公告 / 活动信息”	marketing-automation
“如实总结已上线变更，供发布渠道使用”	changelog-maintenance

第 3 步：收集最小且真实的证据集

不要只凭记忆撰写版本历史。先获取最精简、可信的资料包：

• 已合并的发布 PR、标签或发布条目（如有）
• 此版本包含的已合并 PR / 问题 / 提交
• 关联的迁移文档、升级说明或帮助文档
• 破坏性变更、移除项、弃用项、截止日期或发布注意事项
• 发布渠道限制（CHANGELOG.md、GitHub Release、客户更新中心、Steam 补丁说明帖）
• 自动化背景（如有）

如果证据不完整，请明确标注假设和缺失的证明。

第 4 步：选择最精简且实用的产出资料包

使用 references/output-packets-and-channel-handoffs.md。

默认形式：

• single-entry → 一条变更日志条目或一个版本说明区块
• summary-plus-links → 简短版本摘要，以及迁移 / 帮助 / API 链接
• migration-brief → 变更内容、受影响对象、必需操作、截止日期和相关链接
• patch-note-brief → 简洁的新内容 / 调整 / 修复 / 已知问题资料包
• sync-packet → 版本说明草稿，以及需要保持一致的下游文档或渠道清单

如果一个发布资料包和一份简短的同步清单就足够，就不要提交一本面面俱到的手册。

第 5 步：遵循特定模式的写作规则

• 变更日志：优先分组列出重要变更，而不是逐条梳理提交；如果仓库采用对比链接或版本 / 日期格式，就保留这些内容。
• 版本说明：开篇说明影响，而不是内部工单编号；措辞通俗，便于快速浏览。
• 迁移更新：突出必需操作、受影响读者、截止日期和兼容性风险。
• 游戏补丁说明：保持轻量、面向玩家；不要夹带发布机制或营销宣传文案。

第 6 步：将记录、沟通和推广分开

严格维护以下边界：

• 变更日志 / 版本说明总结已发布的内容
• 如果迁移步骤过多，详细内容应放在关联的迁移文档中
• 教程 / 常见问题解答放在 technical-writing 中
• API 和集成详情放在 api-documentation 中
• 发布 / 回滚机制放在 deployment-automation 中
• 营销宣传文案放在 marketing-automation 中

第 7 步：使用自动化，但不要放弃判断

将自动化结果用作草稿输入，而不是最终编辑稿。

• Release Drafter / 自动生成的版本说明 → 适合整理 PR 并生成初始要点
• Changesets → 适合确定软件包 / 版本意图并汇总单体仓库发布内容
• release-please / semantic-release 风格的流程 → 适合创建发布 PR、更新版本号并生成基于提交的摘要

仍需手动判断：

• 主要受众是谁
• 哪些内容值得重点说明
• 哪些内容需要迁移链接
• 哪些内容应另行整理为帮助 / API / 内部文档

第 8 步：发布前进行可信度检查

使用 references/release-note-quality-checklist.md。

请核实：

1. 每项声明都与已发布或已合并的证据一致。
2. 所选模式符合受众和渠道。
3. 破坏性变更、移除项和截止日期都醒目易见。
4. 明确指出相关文档链接，而不是让说明内容变得臃肿。
5. 在保持真实准确的前提下，资料包尽可能精简。

第 9 步：返回简报或最终产出

完整起草前，建议采用以下简报格式：

# Release Writing Brief

## Mode
- Primary mode:
- Why it fits:
- Audience:
- Output shape:

## Evidence used
- Source of truth:
- Supporting docs / links:
- Assumptions / missing proof:

## Planned artifact packet
1. main release artifact
2. downstream sync / linked-doc follow-up

## Writing notes
- Breaking changes / deadlines:
- Route-outs kept out of scope:
- Channel-specific constraints:

如果用户已要求提供最终产出，请直接按所选资料包及相应结构生成内容。

示例

示例 1：附带迁移链接的变更日志

输入

根据已合并的 PR 列表更新 v2.4.0 的 CHANGELOG.md，并清楚说明 Basic Auth 即将弃用。

推荐输出方向

• 模式：changelog
• 产出形式：summary-plus-links
• 按 Added、Changed、Deprecated、Fixed 等类别分组
• 提供迁移链接或占位符，而不是将完整的身份验证操作步骤写入变更日志

示例 2：面向客户的版本摘要

输入

将这些已发布的产品更新整理成客户愿意阅读的版本说明。

合适的输出方向

• 模式：release-notes
• 输出形式：single-entry 或 summary-plus-links
• 使用以用户获益为主的标题，例如 新增内容、改进、修复
• 将教程或帮助文档更新交由 technical-writing 处理

示例 3：轻量级游戏补丁说明

输入

为我们的最新游戏更新撰写补丁说明，并保持简短。

合适的输出方向

• 模式：game-patch-notes
• 输出形式：patch-note-brief
• 用简洁的章节介绍新增内容、调整、修复和已知问题
• 将上线活动的宣传或营销活动安排交由 marketing-automation 处理

最佳实践

1. 从已发布的事实出发，而不是凭感觉。
2. 确定一个主要受众和一种主要模式。
3. 根据渠道选择满足需求的最简数据包。
4. 将版本摘要、迁移详情、帮助文档、API 文档、发布机制和上线宣传分开处理。
5. 让自动化工具收集草稿素材，但不要把判断工作交给它。
6. 尽早说明重大变更和截止日期。
7. 将补丁说明视为受玩家体验约束的真实工作流，而不只是改名后的变更日志。

参考资料

• Keep a Changelog
• Semantic Versioning 2.0.0
• Release Drafter
• Changesets
• release-please
• GitHub 文档：自动生成版本说明
• Steamworks：事件类型 — 小型更新／补丁说明
• Steamworks：更新游戏 — 最佳实践