リリースノートのテンプレート

テンプレート

角括弧の中はすべてプレースホルダーです。それ以外はすべて、順序も含めて保持する価値があります：ユーザーは自分に影響することを探すので、破壊的変更が最初に来て、社内向けの作業はまったく表示されません。

## [製品] [バージョン] - [日付]

[このリリースが何のためのものかを説明する一文。日常的なリリースでは省略。]

### 破壊的変更
- [何が壊れたか、代わりに何をすべきか、いつまでに。移行手順にリンク。]

### 新機能
- [結果として説明された機能。「フィルターを固定して再利用」であって
  「SavedViewモデルを追加」ではない。]

### 改善
- [何がより速く、より明確に、またはより信頼できるようになったか、
  おおよそどの程度。]

### 修正
- [ユーザーが見た症状であって、コード内の原因ではない。]

セクションが空の場合は見出しを削除してください。空の「修正」セクションは何も修正されなかったかのように読め、下に何もない見出しは、読者にページが読み込まれなかったと思わせます。

同じテンプレート、記入済み

実際のコンテンツを入れるとこのようになります。どのエントリもファイル、ブランチ、チケット番号、人物に言及していないこと、そして破壊的変更が読者が取るべきアクションから始まっていることに注目してください。

## Acme API 4.2 - 2026年8月20日

ページネーションはすべてのリストエンドポイントでカーソルベースになりました。

### 破壊的変更
- `?page=`はすべてのリストエンドポイントで削除されました。前回の
  レスポンスの`nextCursor`の値を使用してください。`?page=`は
  2026年10月1日以降400を返します。移行手順：
  acme.example/docs/pagination

### 新機能
- 受信トレイに保存されたビュー。フィルターを一度固定すれば、
  サイドバーから再利用できます。
- webhookを単一のプロジェクトに限定できるようになりました。

### 改善
- リストエンドポイントは大規模なアカウントで約4倍高速に
  応答します。
- エクスポートジョブは、止まっているように見える代わりに
  進捗を報告するようになりました。

### 修正
- 招待されたメンバーが初めてサインインするまで空のダッシュボードを
  見ることがなくなりました。
- エクスポート内のタイムスタンプはアカウントのタイムゾーンを
  尊重するようになりました。

各セクションに何を入れるか

破壊的変更

締め切りが含まれる唯一のセクションです。何が動かなくなるか、代わりに何をすべきか、そしていつ動かなくなるかを述べてください。まだ日付を決めていない場合は、まだこのセクションを公開しないでください。日付のない破壊的変更は緊急として読まれ、偽の緊急性の連続は、人々があなたのリリースノートを無視することを学ぶ方法です。

新機能

あなたが構築したオブジェクトではなく、結果を説明してください。テストは、あなたのコードを見たことがない誰かにとってもその行が意味をなすかどうかです。「受信トレイに保存されたビュー」は合格です。「SavedViewモデルとその移行を追加」は不合格です。

改善

正直にできる範囲で定量化してください。「速くなった」はほとんど価値がなく、読者はそれを割り引きます。「大規模なアカウントで約4倍速い」は読む価値があり、あなたが責任を問われうる期待を設定します。測定できない場合は、反証可能な方法で何が良くなったかを述べてください。

修正

原因ではなく症状を書いてください。ユーザーはこれらのノートで自分に起きたことを探すので、「招待されたメンバーが空のダッシュボードに着地していた」は見つけやすく、「メンバーシップキャッシュのレース条件を修正」はそうではありません。

バリエーション

4つのセクションはほとんどのリリースに当てはまります。3つのケースで変更が必要です：

• モバイルアプリのリリース。アプリストアは短い新機能フィールドを表示するので、ストアの一覧で読める一文から始め、その後完全なノートにリンクしてください。ストアの審査もビルドを数日間止めることがあるので、ノートはマージ日ではなくリリース日で日付を付けてください。
• APIリリース。APIをバージョン管理するのと同じ方法でノートをバージョン管理し、非推奨の期間をドキュメントだけでなくノート自体に記載してください。API利用者は、まさにあとどれくらい時間があるかを知るためにノートを読みます。
• 社内ツールや管理ツール。「改善」セクションを削除して「修正」に統合してください。社内ユーザーは自分のワークフローが変わったかどうかを気にしますが、長い「改善」セクションはそれを埋もれさせます。

読みやすさを保つ4つのルール

1. あなたのコードを知らない誰かのために書いてください。ファイル名、ブランチ名、チケットID、サービス名、社内のコードネームは書かないでください。
2. ユーザーに見える影響がないものはすべて省いてください。依存関係の更新、リファクタリング、CIの変更、誤字の修正はコミット履歴に属するものであり、リリースノートには属しません。リリースノートが死ぬ最も一般的な方法は、チーム外の誰にも見えない作業で埋め尽くすことです。
3. 1つのエントリ、1つの変更。ある行が「と」という言葉を2回必要とするなら、それはおそらく2つのエントリです。
4. リズムが「出荷するたびに」であっても、人々が頼れるリズムで公開してください。1週間に4回現れてその後2ヶ月現れないノートは、ノイズとして扱われます。

リリースノートの形式：順序通りの各部分

形式は順序ほど重要ではありません。どんな見出しスタイルを使っても、リリースノートに目を通す読者は同じ4つのことを同じ順序で求めており、人気のあるリリースノートの形式はどれもこのバリエーションです。

1. バージョン番号ではなく、読者にとって何が変わったかを述べる見出し。バージョンはその下の小さな行に、日付はどのロケールでも同じように読めるISO形式（2026-08-29）で入ります。
2. 破壊的変更と締め切りがあるものはすべて、小さなものであっても最初に。読者が1段落の後で読むのをやめるなら、これが必要としていた段落です。
3. 何が新しいか、段落あたり1項目、結果を最初の節に置き、「アクション不要」を含む必要なアクションを毎回述べる。
4. 修正と改善、その後は下部に1行のリストとしてそれ以外すべて。依存関係の更新と社内変更は残ります。それを探すただ1人の人が本当に必要としているからです。

Markdownでは、これはH2見出し、控えめなバージョンと日付の行、そして破壊的・新機能・改善・修正のためのH3セクションです。メールでは、見出しを件名にした同じ順序です。changelogウィジェットでは、見出しと最初の段落で、残りはリンクの後ろにあります。上記のテンプレートは、その形をそのまま書き出したものです。

形ではなく執筆そのものについては、ブログの実際に読まれるリリースノートの書き方と保つ価値のあるリリースノートのベストプラクティスをご覧ください。

よくある質問

リリースノートはどのくらいの長さにすべきですか？

ユーザーに影響する変更が必要とする長さだけで、それ以上ではありません。1つのバグ修正だけのリリースは2行で済みます。小さなリリースを重要そうに見せるために水増しすると、人々は大きなものを読み飛ばすようになります。

リリースノートとchangelogの違いは何ですか？

実際には、これらの用語は同じ意味で使われます。チームがそれらを区別する場合、リリースノートは1回のリリースを説明しユーザーのために書かれるのに対し、changelogは時間の経過とともにすべてのリリースを記録する継続的なリストです。このテンプレートは1回のリリースをカバーします。changelogとは、それらを最新のものから積み重ねたときに得られるものです。

リリースノートにバージョン番号を付けるべきですか？

ユーザーがそれを見ることができる場合のみです。バージョン番号は、読者が自分がどのバージョンにいるかを知る必要があるAPI、ライブラリ、インストール済みソフトウェアで役立ちます。継続的にデプロイされるウェブアプリでは、日付の方が便利です。それが、ユーザーが自分の経験と照合できるものだからです。

誰がそれを書くべきですか？

何が変わったかを知っている人、つまり通常はそれをマージしたエンジニアであり、声のトーンを持つ人が編集します。それを作業の外にいる誰かに完全に任せることの失敗パターンは、変更ではなくチケットを説明するノートです。