コンテンツにスキップ

03. 変更履歴の管理

このドキュメントは、プロジェクトの技術的な変更履歴を記録するCHANGELOG.mdファイルの管理と、その自動生成に関するルールを定めます。

1. CHANGELOGの目的と役割

  • 目的:
    • 開発者や技術的なユーザーが、バージョン間の全ての技術的な変更点を正確に追跡できるようにします。
  • 役割:
    • feat（新機能）、fix（バグ修正）、perf（性能改善）、BREAKING CHANGE（破壊的変更）といった、コミット履歴に基づく事実を網羅的に記録します。
  • 配置場所:
    • CHANGELOG.mdファイルは、リポジトリのルートディレクトリに配置します。

リリースノートとの違い

CHANGELOGは、あくまで開発者向けの技術的な変更履歴です。エンドユーザー向けの、より分かりやすい04_リリースノートとは目的と対象読者が異なります。

2. 自動生成の前提条件

CHANGELOG.mdは、手動で編集するのではなく、ツールによって自動生成します。この自動化は、以下の規約が遵守されていることを絶対的な前提とします。

  • Conventional Commits:
    • 全てのコミットメッセージが、05_ブランチ規定で定められたConventional Commits規約に厳密に従っていること。
  • Gitタグ:

ツールは、直近のGitタグから最新のコミットまでの間のコミットメッセージを解析し、変更点を抽出・分類します。

3. 推奨ツール

CHANGELOG.mdの生成とバージョン管理を自動化するために、以下のツールの利用を推奨します。プロジェクトの技術スタックに応じて選択してください。

  • standard-version (JavaScript/Node.js プロジェクト向け)
    • 機能: Git履歴を解析し、次の適切なバージョン番号を判断し、CHANGELOG.mdを更新し、新しいバージョンタグを作成する、という一連の作業を一つのコマンドで実行します。
    • 後継ツール: 現在はconventional-changelog/standard-versionはメンテナンスが終了し、conventional-changelog-cliとconventional-recommended-bumpなどを組み合わせた利用が推奨されています。
  • その他の言語向けツール:
    • 多くの言語で、Conventional Commitsに対応した同様のツールが存在します。（例: Pythonのpython-semantic-releaseなど）

4. 運用フロー

CHANGELOG.mdの更新は、02_リリースプロセスのStep 2: リリースブランチでの最終準備の中で行います。

standard-versionを利用する場合の具体的な手順例

  1. release/vX.Y.Zブランチ上で、全ての最終準備が完了した状態にします。

  2. 以下のコマンドを実行します。

    # まずは--dry-runで、どのような変更が行われるかを確認する
npx standard-version --dry-run
    • このコマンドは、実際にはファイルを変更せず、以下のようなことを行います。
      • featやfixのコミットを基に、次にリリースすべきバージョンを自動で判断します（例: 1.0.0 → 1.1.0）。
      • CHANGELOG.mdに、このv1.1.0の変更点がどのように追記されるかをプレビュー表示します。
      • package.jsonのバージョンがどのように更新されるかを表示します。

  3. プレビュー内容に問題がなければ、本実行します。

    npx standard-version
    • これにより、以下の変更がローカルリポジトリに自動的に適用されます。
      1. package.json（または指定されたファイル）のバージョンが更新されます。
      2. CHANGELOG.mdが更新（または新規作成）されます。
      3. 上記の2つの変更が、chore(release): v1.1.0のようなメッセージでコミットされます。
      4. v1.1.0というGitタグが、そのコミットに対して作成されます。

  4. 最後に、生成されたコミットとタグをリモートリポジトリにプッシュします。

    git push --follow-tags origin release/v1.1.0
    • --follow-tagsオプションにより、コミットと一緒に新しいタグもプッシュされます。

このプロセスにより、手作業によるミスなく、常に一貫したフォーマットのCHANGELOG.mdを維持することができます。