changelogの例

1. 日常的なSaaSリリース

よくあるケース：ユーザーに見える少数の変更、移行なし、ドラマなし。リリースが小さかったので短く、それを水増ししたい衝動に抵抗することがスキルの大半です。

## 2026年8月20日

### 新機能
- 受信トレイに保存されたビュー。フィルターを一度固定すれば、
  サイドバーから再利用できます。

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

### 修正
- 招待されたメンバーが初めてサインインするまで空のダッシュボードを
  見ることがなくなりました。

2. 非推奨を伴うAPIリリース

API changelogの読者は1つのことを探しています：自分の統合が壊れようとしているか、そしてあとどれくらいの時間があるか。それを上部に置き、日付を付けてください。

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

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

### 新機能
- webhookを単一のプロジェクトに限定できます。

### 改善
- リストエンドポイントは10,000件を超えるレコードを持つ
  アカウントで約4倍高速に応答します。

3. モバイルリリース

アプリストアは切り詰められた新機能フィールドを表示し、審査はビルドを数日間止めることがあります。両方の事実がエントリを形作ります。

## iOS 3.4.0 - 2026年8月20日

オフラインモード。接続がなくても開いて、読んで、下書きを
作成できます。オンラインに戻ると、すべてが同期されます。

### このリリースにはさらに
- 古いデバイスでの起動が高速化。
- Mailから共有リンクを開いたときのクラッシュを修正。

4. セキュリティ修正

少なく語ることが正しい唯一のエントリです。ユーザーはアップデートすべきだと知る必要がありますが、他の誰も、まだアップデートしていないバージョンを攻撃するのに十分な正確な説明を必要としません。

## 2026年8月20日

### セキュリティ
- セッショントークンの検証方法を強化しました。セルフホスト型の
  インストールを利用しているアカウントは4.2.1以降に
  アップデートしてください。責任を持って報告されました。
  悪用の証拠はありません。詳細：acme.example/security/2026-08

5. 悪い例はこのように見える

ここにあるすべての行は形としては本物であり、すべての行が間違いです：

## v2.3.7

- feature/inbox-refactorからPR #482をマージ
- lodashを4.17.20から4.17.21に更新
- MembershipCache.resolve()のレース条件を修正
- さまざまなバグ修正と改善
- SavedViewモデルをリファクタリング（Daveありがとう！）

良いものに共通すること

• 実装ではなく結果を説明しています。コードを一度も見たことがない読者でも、そのエントリが自分に影響するかどうかを判断できます。
• 物事を省いています。依存関係の更新、リファクタリング、CIの変更、社内の名前変更は存在せず、その不在が残りを読みやすく保っています。
• コストのかかるものを最初に置いています。何かが壊れる場合、それは日付とともに最初の見出しです。
• 読者が使える方法で日付が付けられています：ユーザーがバージョンを見られる場合はバージョン番号、見られない場合は日付。
• 意図的に退屈です。感嘆符なし、マーケティング用の形容詞なし、「発表できることを嬉しく思います」もなし。changelogを読む人々は情報を探しており、それを妨げるものすべてに苛立つでしょう。

よくある質問

changelogはどんな形式を使うべきですか？

keepachangelog.comは標準に最も近いもので、そのセクション名（Added、Changed、Deprecated、Removed、Fixed、Security）は広く認識されています。それはセクション内の言い回しよりもはるかに重要ではありません。曖昧なエントリを持つ一貫した形式は、具体的なエントリを持つ緩い形式よりも悪いです。

どのくらいの頻度で公開すべきですか？

あなたのリリースに合ったどんなリズムでも、そして一貫して。リリースごとに公開するのが最もシンプルなルールです。1か月分のリリースを1つの投稿にまとめると、後で個々の変更を見つけにくくなります。そしてそれこそが、ほとんどの人が実際にchangelogを読む瞬間です。

changelogは自社サイトにあるべきですか、それともサードパーティのページにあるべきですか？

可能であれば自社サイトです。なぜなら、そこにトラフィックと検索価値が蓄積されるからであり、他人のドメインにあるchangelogは、あなたの製品の一部ではなく、そこから1リンク離れたものになってしまうからです。これは、リンクを張るホスト型ページとしてではなく、自分でレンダリングするフィードとして提供することの根拠です。

ユーザーは本当にchangelogを読みますか？

少数の人が定期的に読み、はるかに多くの人が、何かが自分の足元で変わった瞬間にそれを検索します。その2番目のグループが、原因ではなく症状を書くべき理由です。彼らは自分の言葉で、自分に起きたことを検索しているからです。

参考記事：changelogとリリースノートの違い、そしてKeep a Changelogを実際に実装する。