writing-release-notes

リリースノートの書き方

概要

よくある失敗は、コミットログをそのまま貼り付けることです。正確で網羅的ですが、役に立ちません。コードに何が起きたかを説明している一方で、読者が知りたいのは自分に何が起きるかだからです。

基本原則： 読者が判断するのは二つです。アップグレードするべきか、そしてアップグレードした場合に何が壊れるか。各行はどちらかの判断に役立つか、さもなければ不要な情報です。

関連スキル： 組織内の読者向けには writing-internal-comms、項目からリンクするドキュメントには coauthoring-docs、リリースに破壊的変更が含まれる場合は evolving-apis-and-schemas を使います。

鉄則

EVERY ENTRY STATES WHAT CHANGED FOR THE READER, NOT WHAT CHANGED IN THE CODE

Refactored the auth middleware to use the new token store はコミットメッセージです。Sessions now survive a server restart はリリースノートです。同じ変更でも、読者の疑問に答えているのは一方だけです。

読者に見える影響がない項目は、リリースノートに一切記載しません。コミットログはすでに存在していて、ワンクリックで確認できます。

ステップ 1：どのドキュメントを書くのか把握する

「リリースノート」と呼ばれる成果物は三種類あります。混同しても誰の役にも立ちません。

ドキュメント	対象読者	形式
CHANGELOG	履歴を確認する人	簡潔で累積的。変更ごとに 1 行、種類別に分類し、新しいバージョンから記載
リリースノート	今すぐアップグレードするか判断する人	まず主な変更を示し、その後に全変更を列挙。上位の項目は文章で記載
アップグレードガイド	すでにアップグレードを決めた人	破壊的変更のみを記載し、それぞれ変更前後と手順を示す

小規模なライブラリなら CHANGELOG だけで十分です。破壊的変更を含むリリースでは三種類すべてが必要で、リリースノートでは内容をそのまま載せるのではなく、アップグレードガイドにリンクします。

ステップ 2：情報を集めてから、読者向けに書き換える

git log --oneline v1.4.0..HEAD
git log v1.4.0..HEAD --format='%s%n%b' | grep -iE 'BREAKING|deprecat'
git diff v1.4.0..HEAD --stat -- '*.proto' 'migrations/' 'openapi.yaml'

最も重要なのは最後のコマンドです。コミットの件名には通常記載されない、インターフェースの変更を見つけられます。

次に、候補を一つずつ、次の問いに沿って書き換えます。読者がこれまでできなかったことで、今できるようになったことは何か。あるいは、これまでと動作が変わる点は何か。 答えがなければ、除外します。

ステップ 3：分類する

次の六つをこの順序で使い、該当する変更がない項目は省略します。どれほど些細に見えても、破壊的変更は必ず先頭に置きます。

カテゴリ	含める内容
破壊的変更	読者によるコード、設定、またはデータの変更が必要なもの
追加	新しい機能
変更	互換性はあるものの、既存の動作が変わるもの
非推奨	現時点では動作するが、削除予定のもの。削除されるバージョンも記載
削除	以前に非推奨となり、削除されたもの
修正	バグ。読者が目にした症状を説明
セキュリティ	必ず独立したセクションにし、必ず上部近くに置き、「修正」には埋め込まない

非推奨の告知には日付またはバージョンを記載し、「近日中」とは書きません。 削除時期を示さない非推奨の告知は無視され、その後の削除が予想外のことになってしまいます。

セキュリティに関する項目には、深刻度と対応が必要かどうかを記載します。 CVE が割り当てられている場合は、それも記載します。悪用に特定の設定が必要な場合は、その設定を明記します。読者が知る必要があるのは、アップグレードすべきだということだけでなく、自分が影響を受けているかどうかです。

ステップ 4：項目を記述する

各項目には、何が変わったのか、誰に影響するのか、詳細へのリンクを記載します。CHANGELOG では 1 行にまとめ、目玉機能の場合は 2〜3 文で説明します。

代わりに	こう書く
Fix null pointer in handler	拡張子のないファイルをアップロードするとクラッシュする問題を修正しました
Bump deps	OpenSSL 3.2.1 に更新し、CVE-2024-XXXX を解決しました（対応は不要です）
Add caching layer	10k 件以上のドキュメントがあるワークスペースで、ダッシュボードのクエリが 200ms 未満で返るようになりました
Refactor config parsing	(読者に見える影響がないため省略)
Change API response	破壊的変更： GET /documents が results の代わりに items を返すようになりました。アップグレード前にクライアントを更新してください。詳しくはアップグレードガイドをご覧ください
Improve performance	100MB の CSV のインポートが約 4 倍高速になりました（参照データセットで約 90 秒から約 22 秒に短縮）

品質を大きく左右するルール：

• 仕組みではなく効果から書き始めます。 読者が気にするのはトークンストアではなく、再起動後も使えるかどうかです。
• 数値で示します。 「高速化しました」では検証できませんが、「100MB のインポートが 90 秒から 22 秒に短縮」なら読者が確認でき、はるかに説得力があります。
• バグ修正では症状を明記します。 読者は、実際に使う言葉で問題を検索してリリースノートを探します。
• 対応が必要な場合は明記します。 ほとんどの項目で対応は不要ですが、必要な項目は見落とされないようにしてください。
• 内容をそのまま載せるのではなく、リンクします。 移行手順、ベンチマーク、API の詳細はリンク先のドキュメントに記載します。
• 過去形、能動態で、宣伝文句は使いません。 「セッションが再起動後も維持されるようになりました。」と書きます。「革新的な新しいセッション体験を発表できることを大変うれしく思います。」とは書きません。

ステップ 5：破壊的変更には移行手順を記載する

何が壊れたかを記載しても、どう対応すればよいかが書かれていない項目は不完全です。

### Breaking

**`GET /documents` renames `results` to `items`**

The list envelope now matches every other collection endpoint.

Before:
```json
{ "results": [...], "total": 42 }
```

After:
```json
{ "items": [...], "total": 42 }
```

**Migration:** update clients to read `items`. The old field is still present
in 2.x and will be removed in 3.0. Clients reading `results` continue to work
until then, with a `Deprecation` header on every response.

最善なのは移行コマンドを提示することです。たとえば npx my-tool codemod v3 のようなコマンドがあるなら、そのことを明記します。次善策は差分を示すことです。許容できる最低限は文章での説明です。「ユーザーは連携機能を更新してください」では、いずれにも当てはまりません。

形式

## [2.3.0] — 2026-03-14

### Security
- Fixed a path traversal in the archive importer that allowed writing outside
  the workspace directory (CVE-2026-XXXXX, high). Affects 2.0–2.2 with imports
  enabled. **Upgrade recommended.**

### Breaking
- `GET /documents` returns `items` instead of `results` ([upgrade guide](./UPGRADE.md#23))

### Added
- Full-text search across document bodies, with `search:` filters
- `--dry-run` on `import`, printing what would change without writing

### Changed
- Dashboard queries return in under 200ms for workspaces above 10k documents
- Default session lifetime is now 30 days (was 7); override with `SESSION_TTL`

### Deprecated
- `results` in list responses — removed in 3.0
- `POST /documents/bulk` — use `POST /documents` with an array; removed in 3.0

### Fixed
- Uploading a file with no extension no longer crashes the worker
- Timestamps in exports use the workspace timezone rather than UTC

**Full diff:** [v2.2.1...v2.3.0](https://github.com/org/repo/compare/v2.2.1...v2.3.0)

日付は ISO 形式、バージョンは角括弧で囲んでください。この組み合わせにより CHANGELOG を機械的に解析できるため、後続のツールがこれを前提としています。

バージョンの示し方

バージョン番号もメッセージの一部です。semver では、破壊的変更にはメジャーバージョンの引き上げが必要です。適切に対応するためにリリースを延期するより、マイナーリリースで破壊的変更を出すほうが信頼を損ないます。プロジェクトが 1.0 より前の段階にある場合や、異なるバージョン体系を採用している場合は、読者が判断できるよう CHANGELOG の冒頭に明記してください。

よくある間違い

コミットログをそのまま貼り付ける。 情報は網羅的でも、時系列順で読みにくく、ToolGateway が何なのか知らない読者に内部の命名をさらしてしまいます。

小さな差分だったという理由で、リストの途中に破壊的変更を埋もれさせる。 差分の大きさと読者への影響は関係ありません。

誰からも報告されなかった修正を省く。 問題に遭遇しても、報告しなかった人がいます。修正されたことを知る手段がリリースノートです。

「さまざまなバグ修正と改善」。 何も伝わらず、記録する手間すらかけなかったリリースのように見えます。

内部用語を使う。 チーム外の人には意味が分からないモジュール名、チケット番号、サービス名を記載します。

依存関係の更新を個別に列挙する。 まとめて記載してください。ただし、セキュリティ修正や動作変更を含むものは、独立した項目にします。

日付がない。 読者は日付をもとに、現在使っているバージョンを判断します。

タグを付けるときに記憶を頼りに書く。 変更を加えた時点で項目を追加してください。読者に見える効果が明確なうちに記載できます。