---
id: gh-writing-changelogs
name: "writing-changelogs"
url: https://skills.yangsir.net/skill/gh-writing-changelogs
author: riekelt
domain: writing
tags: ["changelog", "release-notes", "technical-writing", "documentation", "handover"]
install_count: 17200
rating: 4.60 (120 reviews)
github: https://github.com/riekelt/technical-writer/tree/main/plugins/technical-writer/skills/writing-changelogs
---

# writing-changelogs

> 此技能用于在完成有意义的开发工作后编写 changelog 条目、发布说明或‘what shipped’摘要。它能将变更按标准分类（如 Added/Fixed/Breaking），强制将破坏性变更置于最前并注明迁移操作，同时遵循诚实约定记录已知问题、遗留事项和刻意省略，确保发布文档准确、可追溯。适用于技术团队快速生成高质量变更记录，避免遗漏关键信息。

**Stats**: 17,200 installs · 4.6/5 (120 reviews)

## Before / After 对比

### 发布说明生成效率对比

**Before**:

用户在没有此技能前，需要手动从 git 提交记录和口口相传中整理变更，容易遗漏破坏性变更，格式不统一，还要反复核对已部署和已验证状态，每次发布前要花大量时间梳理，最终产出的 changelog 可读性差，读者难以快速定位重要变更。

**After**:

此技能自动生成结构化 changelog，按标准分类列出变更，破坏性变更置顶并附带迁移操作，诚实记录已知问题和遗留事项，用户只需提供变更事实即可快速产出可发布的说明，显著减少撰写时间并提升文档质量。

| Metric | Before | After | Change |
|---|---|---|---|
| 发布说明撰写时长 | 60分钟 | 10分钟 | -83% |

## Readme

# Writing changelogs

**REQUIRED BACKGROUND:** the `technical-writing` skill (hard rules, truth rules, style).

## Overview

The changelog is one of the few document types where the change, not the current state, is the subject; migration docs and release notes are the others. 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 (roughly three changed files, or three commits), and never rewrite or delete existing entries.

## Rules

- One entry per shipped change, newest first, ISO dates, grouped by version where versions exist.
- 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, and no jargon the reader would not know.
- Group related changes, and 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. Both draw on the same sources and must never contradict each other.

## 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. The bold lead carries the user impact, which is what lets a reader triage a change list.

## Honesty conventions

Three entry types make a changelog 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 implemented, deployed, or verified unless that exact action was completed and checked. Distinguish implemented (in the repo) from deployed (live) from externally verified.

## Handover / completion summary

For handing finished work to a reviewer or operator, cover these sections in order:

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.


---
*Source: https://skills.yangsir.net/skill/gh-writing-changelogs*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-writing-changelogs/markdown*