変更履歴を迷子にしないCHANGELOGの書き方：Web制作・運用で使う最小ルール
CHANGELOGは、サイトやツールに加えた変更を時系列で残すための更新履歴です。WordPressテーマの修正、プラグイン設定の変更、サーバー設定の調整、自動化スクリプトの更新などで「いつ、何を、なぜ変えたか」を後から追えるようにします。
特に実務では、Gitのコミットログだけでは足りない場面があります。コミットログは開発者向けの細かい作業記録になりがちですが、CHANGELOGは運用担当者、制作者、依頼者、未来の自分が読むための要約です。
この記事では、初心者でも使いやすいCHANGELOGの考え方と、Markdownで書ける基本形を整理します。
- CHANGELOGは「利用者や運用担当者に伝える変更の要約」
- Gitの履歴とは別に、リリース単位・作業単位で残すと読みやすい
Added、Changed、Fixed、Removedのように種類で分けると実務で探しやすい- WordPressやサーバー運用では、変更理由と影響範囲も一言添えると後から助かる
CHANGELOGとは何を残すファイルか
CHANGELOGは、変更の事実を読む人向けに整理した記録です。
たとえばWordPressサイトで「問い合わせフォームが送信できない」という不具合を直したとします。このとき、GitにはCSSやPHP、設定ファイルの差分が残るかもしれません。しかし運用担当者が知りたいのは、まず次のような情報です。
- 何が直ったのか
- どのページや機能に関係するのか
- いつ反映されたのか
- 既存の使い方に影響があるのか
CHANGELOGは、この情報を短くまとめます。
## [1.2.1] - 2026-07-08
### Fixed
- 問い合わせフォームで送信完了画面に進めない問題を修正しました。
- 対象: `/contact/` ページ
ここで重要なのは、コード差分そのものではなく、変更の意味を残すことです。ファイル名や関数名だけでは、数か月後に見返したときに「何のための変更だったか」が分かりにくくなります。
GitのコミットログとCHANGELOGの違い
CHANGELOGはGitの代わりではなく、Gitの履歴を人が読める形にまとめ直すものです。
Gitのコミットログは、開発作業の単位で細かく残ります。たとえば「フォーム処理を修正」「バリデーションを調整」「文言を変更」のように、1つの不具合対応でも複数のコミットに分かれることがあります。
一方、CHANGELOGでは読者が知りたい単位にまとめます。
| 記録 | 主な読者 | 向いている内容 |
|---|---|---|
| Gitコミットログ | 開発者 | どのファイルをどう直したか、作業の細かい履歴 |
| CHANGELOG | 運用担当者、制作者、利用者、将来の開発者 | 何が追加・変更・修正されたか、利用上の影響 |
| リリースノート | 利用者、顧客、社内関係者 | 大きな変更点、注意点、告知したい内容 |
ここがポイント: Gitは「作業の証跡」、CHANGELOGは「変更内容の案内」と考えると使い分けやすくなります。
Web制作やWordPress運用では、開発者以外も変更履歴を見ることがあります。そのため、CHANGELOGには専門的すぎる差分名だけでなく、画面名、機能名、影響範囲を入れると実務で使いやすくなります。
基本の書き方：Markdownで十分に始められる
CHANGELOGは、最初から複雑な形式にする必要はありません。まずはMarkdownファイルとして CHANGELOG.md を作り、日付またはバージョンごとに変更を並べるだけで始められます。
一般的には、プロジェクトのルートに次のようなファイルを置きます。
my-project/
├── README.md
├── CHANGELOG.md
├── src/
└── package.json
最小構成の例
小規模なWebサイトや社内ツールなら、次の形で十分です。
# Changelog
## [1.1.0] - 2026-07-08
### Added
- 管理画面にCSVエクスポート機能を追加しました。
### Changed
- お知らせ一覧の表示件数を5件から10件に変更しました。
### Fixed
- スマホ表示でフッターのリンクが折り返される問題を修正しました。
この例では、変更の種類を見出しで分けています。
Added: 新しく追加した機能Changed: 既存機能の変更Fixed: 不具合修正Removed: 削除した機能や設定Deprecated: 将来削除予定の機能Security: セキュリティ関連の修正
この分類は、Keep a Changelog で紹介されている考え方が参考になります。厳密に合わせる必要はありませんが、種類で分けると「何が変わったのか」を短時間で探せます。
日付だけで管理する場合
バージョン番号を付けていないWeb制作案件では、日付単位でも構いません。
# Changelog
## 2026-07-08
### Fixed
- WordPressの固定ページ「会社概要」で、スマホ表示時に表が横にはみ出す問題を修正しました。
### Changed
- トップページのキャンペーンバナーを7月分の内容に差し替えました。
バージョンを切らない運用では、日付だけのほうが続けやすいことがあります。大事なのは形式を立派にすることではなく、後から探せる粒度で残し続けることです。
実務で使う入力例と出力例
CHANGELOGは、変更メモをそのまま貼るだけでは読みづらくなります。ここでは、作業メモを読者向けの更新履歴に整える例を見ます。
入力例：作業中のメモ
- contact form 送信後に500。メール本文テンプレートの変数名ミス。
- wp plugin update: SEO plugin 4.2.1 -> 4.3.0
- cronの実行時間を毎時から15分ごとにした
- LPのCTA文言変更。無料相談 -> お問い合わせ
このままだと、作業者本人には分かっても、他の人には伝わりにくい部分があります。500 がどの画面で起きたのか、プラグイン更新で何に注意すべきか、cron変更が何の処理に関係するのかが不足しています。
出力例：CHANGELOGに載せる形
## 2026-07-08
### Fixed
- 問い合わせフォーム送信時にサーバーエラーが表示される問題を修正しました。
- 原因: メール本文テンプレート内の変数名不一致
- 対象: `/contact/`
### Changed
- SEO関連プラグインを 4.2.1 から 4.3.0 に更新しました。
- 定期実行処理の間隔を1時間ごとから15分ごとに変更しました。
- 対象: 在庫データの同期処理
- ランディングページのCTA文言を「無料相談」から「お問い合わせ」に変更しました。
ここでは、作業メモを少しだけ補っています。ポイントは、読む人が次の確認に進めることです。
- 不具合なら、対象画面と原因を残す
- 更新なら、更新前後のバージョンを残す
- 自動化なら、実行間隔や対象処理を残す
- 文言変更なら、変更前後の言葉を残す
すべてを長く書く必要はありません。変更の意味が伝わる最低限の情報を足すだけで、後日の調査がかなり楽になります。
WordPress・サーバー運用で残しておきたい変更
Web制作や運用では、見た目の変更だけでなく、裏側の設定変更もCHANGELOGに残す価値があります。
特に初心者が見落としやすいのは、管理画面で行った変更です。テーマファイルの編集はGitに残っても、WordPress管理画面の設定変更やサーバーコントロールパネル上の操作は、別途記録しないと消えやすくなります。
残すと役立つ変更
次のような変更は、CHANGELOGに書いておくとトラブル調査で効きます。
- WordPress本体、テーマ、プラグインの更新
- 問い合わせフォーム、予約フォーム、決済設定の変更
- リダイレクト、SSL、キャッシュ、CDNの設定変更
- cronや予約投稿など、定期実行に関わる変更
- API連携先、送信先メールアドレス、Webhook URLの変更
- 表示速度改善のための画像圧縮、遅延読み込み、キャッシュ設定
たとえば「昨日からフォーム通知が届かない」と言われたとき、CHANGELOGにメール送信設定の変更が残っていれば、調査の出発点がすぐ決まります。
書かなくてもよい変更
一方で、何でも書くとCHANGELOGは読まれなくなります。
たとえば次のような内容は、通常はGitのコミットログやタスク管理ツールに任せてもよいでしょう。
- 誤字1文字の修正で、利用者への影響がほぼないもの
- 作業途中の一時的な変更
- コード整形だけの変更
- 公開前の試行錯誤で、最終状態に残らないもの
判断に迷う場合は、「この変更を知らないと、後で調査や引き継ぎに困るか」で考えると決めやすくなります。
バージョン番号を付けるならSemVerを知っておく
公開ツールや複数人で使うスクリプトでは、バージョン番号を付けると変更の大きさを伝えやすくなります。
代表的な考え方に Semantic Versioning があります。形式は MAJOR.MINOR.PATCH です。
1.4.2
それぞれの意味は、ざっくり次のように考えます。
MAJOR: 使い方が変わる大きな変更MINOR: 互換性を保った機能追加PATCH: 不具合修正や小さな改善
たとえば、CSVを読み込むCLIツールを作っている場合、次のように分けられます。
## [2.0.0] - 2026-07-08
### Changed
- 入力オプションを `--file` から `--input` に変更しました。
## [1.3.0] - 2026-06-20
### Added
- JSON形式での出力に対応しました。
## [1.2.1] - 2026-06-12
### Fixed
- 空行を含むCSVで集計件数がずれる問題を修正しました。
2.0.0 のような大きな番号変更は、利用者に「使い方が変わるかもしれない」と知らせる役割を持ちます。社内用スクリプトでも、実行コマンドや出力形式が変わる場合は、バージョン番号で目印を付けると引き継ぎが楽になります。
よくある失敗と改善例
CHANGELOGでつまずきやすいのは、書き方が難しいからではありません。たいていは「誰に向けて何を残すか」が曖昧なまま書き始めることが原因です。
失敗1: コミットメッセージの貼り付けになる
NG例です。
### Fixed
- fix bug
- update css
- modify form
これでは、何が変わったのか分かりません。改善すると次のようになります。
### Fixed
- スマホ表示で送信ボタンが画面外にはみ出す問題を修正しました。
- 問い合わせフォームの必須項目エラーが表示されない問題を修正しました。
ファイル名よりも、画面で起きていた現象を優先して書くと伝わりやすくなります。
失敗2: 変更理由が抜ける
設定変更では、理由が抜けると後で戻してよいのか判断できません。
### Changed
- キャッシュ時間を変更しました。
このままだと、何のために変えたのか分かりません。
### Changed
- お知らせ一覧の反映遅延を減らすため、ページキャッシュの保持時間を24時間から1時間に変更しました。
理由が一文あるだけで、将来の担当者が「速度を優先するのか、即時反映を優先するのか」を判断しやすくなります。
失敗3: 秘密情報を書いてしまう
APIキー、パスワード、認証トークン、個人情報はCHANGELOGに書きません。
### Changed
- APIキーを `sk_xxxxxxxxx` に変更しました。
これは避けるべき書き方です。安全に書くなら、値そのものではなく変更の事実だけを残します。
### Changed
- 外部API連携用の認証キーを再発行し、サーバー側の環境変数を更新しました。
秘密情報は、環境変数、シークレット管理サービス、サーバー管理画面など、適切な場所で扱います。CHANGELOGには「何をしたか」と「影響範囲」を残せば十分です。
自動化するなら「下書き生成」から始める
CHANGELOGは手書きで始めるのが簡単ですが、変更が増えると更新漏れが起きます。そこで、Gitのタグやコミットから下書きを作り、人が整える運用にすると続けやすくなります。
Node.jsのプロジェクトなら、standard-version や release-please のようなリリース支援ツールが使われることがあります。GitHubを使っているなら、リリース作成画面でタグ間の変更からリリースノートを自動生成する機能もあります。
ただし、完全自動で読者向けの文章になるとは限りません。自動生成はあくまで材料集めです。
手動と自動化の使い分け
| 方法 | 向いている場面 | 注意点 |
|---|---|---|
| 手書き | 小規模サイト、WordPress運用、社内ツール | 更新漏れを防ぐため、作業完了時の確認項目に入れる |
| コミットから下書き生成 | Git運用が定着している開発チーム | コミットメッセージの粒度が荒いと読みにくい |
| リリースツール連携 | npmパッケージ、CLI、継続的に配布するツール | バージョン管理とリリース手順の設計が必要 |
初心者のうちは、まず CHANGELOG.md を手で書く形で十分です。慣れてきたら、リリース前にGitの差分を見てCHANGELOGへ転記する、という流れを作ると無理がありません。
すぐ使えるCHANGELOGテンプレート
最初の1枚として使うなら、次のテンプレートで始められます。
# Changelog
このファイルには、サイト・ツール・スクリプトの主な変更を記録します。
## [Unreleased]
### Added
-
### Changed
-
### Fixed
-
### Removed
-
## [1.0.0] - 2026-07-08
### Added
- 初回公開しました。
Unreleased は、まだ公開していない変更を一時的に置く場所です。リリース時に日付やバージョン番号を付けて下へ移動します。
WordPress案件でバージョン番号を使わないなら、こちらのほうが自然です。
# Changelog
## 2026-07-08
### Added
-
### Changed
-
### Fixed
-
### Notes
- 影響範囲:
- 確認したページ:
- 戻す場合の注意:
Notes を入れておくと、サーバー設定や管理画面操作の補足を書きやすくなります。ただし、ここにも秘密情報や個人情報は書かないようにします。
まず決めるべき運用ルール
CHANGELOGは、書式よりも運用ルールを先に決めると続きます。
最初に決めるのは、次の4点で十分です。
- どのファイルに書くか: 例
CHANGELOG.md - どの単位で書くか: 日付単位、バージョン単位、リリース単位
- 誰向けに書くか: 開発者向け、運用担当者向け、利用者向け
- 何を必ず書くか: 変更内容、対象画面、影響範囲、注意点
この4点が決まっていれば、細かい文体は後から整えられます。
実務で特に見るべきなのは、次の変更です。
- 表示や入力フォームの不具合修正
- プラグイン、ライブラリ、サーバー設定の更新
- API連携、メール送信、定期実行の変更
- 既存の操作手順が変わる変更
CHANGELOGは、きれいな文章を書くための場所ではありません。変更後に困った人が、最短で原因に近づくための地図です。次の作業から1行だけでも残し始めると、数週間後の調査で効いてきます。