ソフトウェアのリリースノートとは:書く内容と4つの種類

ソフトウェアのリリースノートとは、ソフトウェアのあるバージョンに添える文書で、そのバージョンで何が変わったか、誰に影響するか、読者が何かしなければならないかを伝える。リリースごとに一度書かれ、アップグレードするか決める人、遭遇した問題が直ったかを確かめる人、製品をサポートする人が読む。良いリリースノートは、短く、そのバージョンに即して具体的で、壊れるものについて正直だ。

ソフトウェアのリリースノートとは何か

1つのリリースについて、日付とバージョンのついた要約だ。その場にいなかった読者の3つの問いに答える。何が違うのか、自分に関係があるのか、自分は何かすべきなのか。プロジェクトの全履歴はチェンジログで、コミットログはコードを書いた人のためのものだ。

同じ事実が、チェンジログのエントリにもリリースノートにも載ることがある。違いは、選び方と読者だ。チェンジログは目立った変更をすべて並べるが、リリースノートは読者が気づく変更を先頭に置いて説明する。その線引きは、チェンジログとリリースノートの違いで詳しく説明している。

ソフトウェアのリリースノートには何を含めるべきか

バージョンと日付、1段落の要約を書き、そのあと変更を、読者がそれで何をできるかでグループ化して並べる。各変更について、読者の言葉で何が違うのか、誰に影響するのか、対応が必要かを書く。

完全な形には、次の部分がある。

1. バージョン番号とリリース日。 タグと同じ形式にして、読者がノートとビルドを突き合わせられるようにする。
2. 要約。 2、3文で、このリリースが何のためのもので、アップグレードに読者の対応が必要かを書く。
3. 新機能と改善。 コードに何が入ったかではなく、読者が何をできるようになったか。
4. 修正。 解消した症状と、それが始まったバージョン。
5. 破壊的変更と非推奨化。 何が、いつ動かなくなり、代わりに何を使うか。あるなら最初に置く。
6. 既知の問題。 出荷したが正しくないと分かっているもの。回避策があれば添える。
7. 要件とアップグレード手順。 対応プラットフォーム、最小バージョン、移行のコマンド。

リファクタリング、目に見える効果のない依存関係の更新、社内のチケットは載せない。読者が気づけない変更は、gitの履歴に任せればいい。言葉遣いと順序はリリースノートの書き方で扱っている。

ソフトウェアのリリースノートは実際にどう見えるか

架空のコマンドラインツールの短い例を示す。内容より、形が大事だ。

## 2.4.0 (2026-10-08)

Faster exports and one breaking change to the config file. Upgrade
needs a one-line edit to `tool.yml`.

### Breaking
- `output:` in `tool.yml` is now `export.path:`. Old configs fail
  with "unknown key". Rename the key; nothing else changes.

### New
- Exports stream to disk, so files over 100 MB no longer time out.

### Fixed
- Search works again for queries containing a hyphen. Broken
  since 2.3.0.

### Known issues
- Windows paths longer than 260 characters still fail. Use a
  shorter output directory for now.

破壊的変更が最初にあり、読者が実際に目にするエラーメッセージの文面が書かれている。人はエラーメッセージで検索するからだ。修正のエントリは壊れたバージョンを挙げているので、読者は自分の問題が始まった時期と照らし合わせられる。既知の問題には回避策があり、何も言わないよりずっといい。エントリの種類ごとの書き方は、リリースノートの例にさらに載せている。

読者ごとにソフトウェアのリリースノートはどう変わるか

情報源は1つに保ち、読者ごとに版を書く。事実は変わらないが、詳しさが変わる。顧客は利点を1行で知りたい。管理者は要件と既知の問題を、開発者は正確な名前とバージョンを、サポートはチケットが来たときに何と答えるかを知りたい。

APIの製品では、開発者向けの版にもっとも注意が要る。作った側には小さな修正でも、呼び出す側には障害になりうるからだ。この読者については、APIチェンジログと破壊的変更で扱っている。社内向けの版では、顧客には要らないがサポートと営業に必要なものを社内向けリリースノートで説明している。

ソフトウェアのリリースノートはどこに公開すべきか

読者が疑問を持ったとき、すでにいる場所に公開する。モバイルアプリならストアの掲載ページで、プラットフォームがバージョンごとにリリースノートの欄を用意している。Appleはビルドにリリースノートを付ける方法を公開している。Web製品なら、アプリからリンクしたチェンジログのページだ。ライブラリならリリースのページとリポジトリ内のファイルで、これはGitHubのリリースノートで説明している。

すべてのバージョンを安定したURLに置き、サポートがリンクできるようにして、古いバージョンも残す。バージョン2.2を使っている読者には、2.3と2.4のノートも必要だ。構成から始めたいなら、リリースノートのテンプレートに、コピーできる見出しがある。

ソフトウェアのリリースノートはどのくらいの長さにすべきか

変更に必要なだけ、それ以上は書かない。パッチリリースなら3行でいい。移行を伴うメジャーリリースなら1ページ必要で、おそらくノートからリンクした別の移行ガイドも要る。判断の基準は、最初の1画面だけを流し読みした読者が、そのリリースが自分に関係するかを分かるかどうかだ。分からないなら、要約を上に動かし、残りを削る。何が通用し、何が習慣にすぎないかは、リリースノートのベストプラクティスにまとめている。

FAQ

ソフトウェアのリリースノートとは何か? ソフトウェアの1つのリリースで何が変わったかを、使う人やサポートする人に向けて、バージョンごとにまとめたものだ。新機能、修正、破壊的変更、読者が対応すべきことを扱う。

リリースノートとチェンジログの違いは何か? チェンジログは、目立った変更の完全で継続的な記録だ。リリースノートは、1つのリリースについてのメッセージで、アップグレードするか決める読者に向けて、選んで書き直したものだ。多くのチームは、バージョンのチェンジログのエントリをそのままリリースノートとして公開している。

ソフトウェアのリリースノートは誰が書くのか? たいてい、プロダクトマネージャー、テクニカルライター、変更をリリースしたエンジニアのいずれかが書き、別の人がトーンを確認する。変更にいちばん近い人が下書きを書き、もう1人が読者の目線で編集すると、いちばん良い結果になる。

マイナーリリースにもリリースノートは必要か? 必要だが、短くていい。パッチリリースでも、何を直したか、読者が対応すべきかは書く。1行のノートでも、ないよりいい。「バグ修正と改善」では、読者に何も伝わらないからだ。

この記事の技術的な記述は第三者による確認を受けていません。誤りがあればお知らせください。修正します。

changeloopの関連ページ： リリースノートのテンプレート, changelogの例