英語でCHANGELOGを書くよう求められたとき、何をどの粒度で書けばいいか迷った経験はないだろうか。
CHANGELOGはバージョンごとの変更内容を開発者向けに記録するドキュメントだ。国際標準の「Keep a Changelog」形式を押さえれば、英語でも問題なく書ける。
この記事では、CHANGELOGに必要な構成要素と6つの変更カテゴリ、そのまま使える日英テンプレートを紹介する。コピペして使えばすぐにプロジェクトで活用できる。
CHANGELOGに必要な構成要素
CHANGELOG（変更履歴）は「Keep a Changelog」という事実上の国際標準がある。以下が標準的な構成要素になる。
- ヘッダー・運用ルール（Header）
- 未リリース（Unreleased）セクション
- バージョンごとのエントリ（Released Versions）
- 6つの変更カテゴリ（Added / Changed / Deprecated / Removed / Fixed / Security）
CHANGELOGとリリースノートの違い
CHANGELOGは「開発者向け」に全変更を時系列で淡々と記録する文書だ。一方、リリースノートは「ユーザー向け」に重要な変更をわかりやすく伝える告知文になる。CHANGELOGが原本で、リリースノートはその編集版という関係だ。
リリースノートの書き方は英語リリースノートの書き方でも確認してほしい。
なぜ英語で書くのか
CHANGELOGはOSSの利用者・コントリビューター・将来の自分が「いつ何が変わったか」を確認する一次情報だ。英語で書くことで、世界中の利用者がアップグレード判断をできるようになる。
「人間が読むための変更履歴」がKeep a Changelogの基本思想だ。gitのコミットログをそのまま貼り付けるのはアンチパターンとされる。
テンプレートをダウンロード（Word）
以下のWordファイルをダウンロードして、プロジェクトに合わせてカスタマイズして使ってほしい。表の列・行はそのまま追加・削除できる。
📥 日本語テンプレートをダウンロード（Word）
📥 Download English Template (Word)
日本語版テンプレート（コピペOK）
ヘッダー・運用ルール
| 項目 | 内容 |
|---|---|
| タイトル | 変更履歴（Changelog） |
| 準拠形式 | Keep a Changelog 1.1.0 に準拠 |
| バージョニング | セマンティックバージョニング（SemVer）に準拠 |
| 並び順 | 新しいバージョンを上に書く（降順） |
未リリースセクション
| 項目 | 内容 |
|---|---|
| セクション名 | [未リリース]（Unreleased） |
| 目的 | 次のリリースに含まれる変更を先行して記録する |
| 運用 | PRマージ時にこのセクションへ追記し、リリース時にバージョン番号へ付け替える |
バージョンエントリの形式
| 項目 | 内容 |
|---|---|
| 見出し | [1.2.0] – 2026-06-12（バージョン番号と日付） |
| 日付形式 | YYYY-MM-DD（ISO 8601） |
| 変更の書き方 | 1変更1行。ユーザー視点で「何が変わったか」を書く |
| 参照リンク | 関連するIssue・PR番号を末尾に付ける（例：(#123)） |
6つの変更カテゴリ
| カテゴリ | 用途 | 記載例 |
|---|---|---|
| Added（追加） | 新機能の追加 | CSVエクスポート機能を追加 (#120) |
| Changed（変更) | 既存機能の仕様変更 | 検索APIのデフォルト件数を20件から50件に変更 (#125) |
| Deprecated（非推奨） | 将来削除される機能の予告 | v1系API を非推奨化。v2.0で削除予定 (#130) |
| Removed（削除） | 機能の削除 | レガシー認証方式を削除 (#131) |
| Fixed（修正） | バグ修正 | タイムゾーン変換で日付がずれる問題を修正 (#128) |
| Security（セキュリティ） | 脆弱性対応 | 依存ライブラリの脆弱性（CVE-XXXX-XXXX）に対応 (#133) |
英語版テンプレート（コピペOK）
Header
| Item | Details |
|---|---|
| Title | Changelog |
| Format | All notable changes are documented based on Keep a Changelog 1.1.0. |
| Versioning | This project adheres to Semantic Versioning. |
| Order | Latest version first (descending). |
Unreleased Section
| Item | Details |
|---|---|
| Section Name | [Unreleased] |
| Purpose | Track upcoming changes before the next release. |
| Workflow | Add entries when PRs are merged; rename to a version number at release time. |
Version Entry Format
| Item | Details |
|---|---|
| Heading | [1.2.0] – 2026-06-12 (version number and date) |
| Date Format | YYYY-MM-DD (ISO 8601) |
| Entry Style | One change per line, written from the user’s perspective. |
| References | Append related issue/PR numbers (e.g., (#123)). |
Six Categories of Changes
| Category | Use For | Example |
|---|---|---|
| Added | New features | Added CSV export support. (#120) |
| Changed | Changes to existing functionality | Changed the default search limit from 20 to 50. (#125) |
| Deprecated | Features to be removed soon | Deprecated the v1 API. It will be removed in v2.0. (#130) |
| Removed | Removed features | Removed the legacy authentication method. (#131) |
| Fixed | Bug fixes | Fixed a date shift issue in timezone conversion. (#128) |
| Security | Vulnerability fixes | Addressed a dependency vulnerability (CVE-XXXX-XXXX). (#133) |
記載例（CHANGELOG.md全体イメージ）
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).
## [Unreleased]
### Added
- Dark mode support for the dashboard. (#140)
## [1.2.0] - 2026-06-12
### Added
- Added CSV export support. (#120)
### Changed
- Changed the default search limit from 20 to 50. (#125)
### Fixed
- Fixed a date shift issue in timezone conversion. (#128)
## [1.1.0] - 2026-05-01
### Added
- Added Slack notification integration. (#110)各セクションの書き方と例文
テンプレートを埋めるときに悩みやすいポイントを解説する。
変更エントリの書き方（ユーザー視点で動詞から）
エントリは過去形の動詞で始め、「ユーザーにとって何が変わったか」を書く。実装の詳細やコミットメッセージの転記は避ける。
| 日本語 | 英語 |
|---|---|
| 〇〇機能を追加 | Added [feature]. |
| 〇〇のデフォルト値を変更 | Changed the default value of [setting]. |
| 〇〇の問題を修正 | Fixed an issue where [problem]. |
| 〇〇を非推奨化 | Deprecated [feature]. |
| 〇〇のサポートを削除 | Removed support for [feature]. |
破壊的変更（Breaking Change）の書き方
破壊的変更はユーザーのアップグレード判断に直結する。BREAKING表記と移行方法をセットで書くのが親切だ。
| 日本語 | 英語 |
|---|---|
| 破壊的変更：〇〇を変更しました | BREAKING: Changed [behavior]. |
| 〇〇からの移行は△△してください | To migrate from [old], do [steps]. |
| この変更には設定の更新が必要です | This change requires updating your configuration. |
| 旧形式はv3.0まで動作します | The old format will continue to work until v3.0. |
| 詳細は移行ガイドを参照してください | See the migration guide for details. |
READMEの書き方は英語READMEの書き方でも確認してほしい。
CHANGELOGでよく使う英語表現
実務でよく使う英語表現を場面別にまとめた。
バージョニング・リリースの基本用語
| 日本語 | 英語 |
|---|---|
| 変更履歴 | Changelog |
| セマンティックバージョニング | Semantic Versioning (SemVer) |
| メジャー／マイナー／パッチ | Major / Minor / Patch |
| 破壊的変更 | Breaking Change |
| 後方互換性 | Backward Compatibility |
| 非推奨 | Deprecated |
| 移行ガイド | Migration Guide |
| プレリリース | Pre-release |
レビュー・運用のフレーズ
| 日本語 | 英語 |
|---|---|
| CHANGELOGの更新を忘れずに | Don’t forget to update the changelog. |
| この変更はUnreleasedに追記してください | Please add this change to the Unreleased section. |
| これは破壊的変更にあたりますか | Does this count as a breaking change? |
| パッチリリースで対応します | We’ll address this in a patch release. |
| 変更履歴に記載のない変更です | This change is not documented in the changelog. |
PRの書き方は英語プルリクエストの書き方でも参考にしてほしい。
まとめ：英語CHANGELOGは6つのカテゴリで完成する
英語CHANGELOGに必要な構成要素を整理した。
- Keep a Changelog形式（Added/Changed/Deprecated/Removed/Fixed/Security）に準拠する
- エントリは「ユーザーにとって何が変わったか」を1行で書く
- Unreleasedセクションで次リリースの変更を先行記録する
- 破壊的変更はBREAKING表記＋移行方法をセットで書く
テンプレートをコピーして、リポジトリ直下の CHANGELOG.md に配置してほしい。特にPRマージ時にUnreleasedへ追記する運用を定着させることで、リリース直前の「変更内容の掘り起こし」作業がなくなる。
コメント