詳細な移行ガイド付き破壊的変更

包括的な破壊的変更メッセージの作成

破壊的変更が大きい場合、コミットメッセージのボディはミニ移行ガイドとして機能すべきです。これは、changelogでコミットを見る外部コンシューマーを持つライブラリやAPIにとって特に重要です。

完全な例

feat(config)!: replace JSON config with YAML format

Migrate the application configuration from config.json
to config.yaml. The YAML format supports comments,
multi-line strings, and anchors, which were frequently
requested by users.

Before:
  {
    "port": 3000,
    "database": {
      "host": "localhost",
      "port": 5432
    }
  }

After:
  port: 3000
  database:
    host: localhost
    port: 5432

BREAKING CHANGE: config.json is no longer read. Rename
your configuration file to config.yaml and convert the
syntax from JSON to YAML. A migration script is available
at scripts/migrate-config.js.

移行ボディの構造

よく構造化された破壊的変更のボディには：

1. 何が変わったか — 変更を説明する1-2文
2. なぜ変わったか — 動機（パフォーマンス、ユーザーリクエスト、簡素化）
3. 変更前後の例 — 具体的なコードや設定のスニペット
4. 移行手順 — ユーザーがすべきことの番号付きリスト
5. 移行ツール — スクリプト、codemod、ドキュメントへの言及

ボディの行折り返し

ボディ行は72文字以内に収めてください。以下での可読性を確保します：

• git log（4スペースのインデントを追加）
• GitHubのコミット詳細ビュー
• コミットをそのまま表示するchangelogジェネレーター

複数の破壊的変更

単一のコミットが複数の破壊的変更を導入する場合、フッターに各項目を記載：

feat!: overhaul API response format

BREAKING CHANGE: Response envelope changed from
{ data, error } to { result, errors }.

BREAKING CHANGE: Pagination now uses cursor-based
pagination instead of offset-based. The page and
per_page query params are replaced by cursor and limit.