changelog-generator

変更履歴ジェネレーター

Tier: 高性能
Category: エンジニアリング
Domain: リリース管理／ドキュメント

概要

このスキルを使うと、Conventional Commits から一貫性があり監査可能なリリースノートを作成できます。コミットの解析、セマンティックバージョンの更新ロジック、変更履歴のレンダリングを分離しているため、編集上の制御を失わずにリリースを自動化できます。

主な機能

• Conventional Commit のルールに従ってコミットメッセージを解析する
• コミットの流れからセマンティックバージョンの更新（major、minor、patch）を検出する
• Keep a Changelog のセクション（Added、Changed、Fixed など）をレンダリングする
• Git の範囲指定または指定されたコミット入力からリリース項目を生成する
• 専用のリンタースクリプトでコミット形式を適用する
• 機械可読な JSON 出力による CI 統合をサポートする

使用するタイミング

• リリースタグを公開する前
• CI でリリースノートを自動生成するとき
• PR チェックで無効なコミットメッセージ形式をブロックするとき
• パッケージごとの変更履歴でスコープによるフィルタリングが必要なモノレポで
• 生の Git 履歴をユーザー向けのリリースノートに変換するとき

主なワークフロー

1. Git から変更履歴項目を生成する

python3 scripts/generate_changelog.py \
  --from-tag v1.3.0 \
  --to-tag v1.4.0 \
  --next-version v1.4.0 \
  --format markdown

2. stdin／ファイル入力から項目を生成する

git log v1.3.0..v1.4.0 --pretty=format:'%s' | \
  python3 scripts/generate_changelog.py --next-version v1.4.0 --format markdown

python3 scripts/generate_changelog.py --input commits.txt --next-version v1.4.0 --format json

3. CHANGELOG.md を更新する

python3 scripts/generate_changelog.py \
  --from-tag v1.3.0 \
  --to-tag HEAD \
  --next-version v1.4.0 \
  --write CHANGELOG.md

4. コミットから次のバージョンを算出する

次のバージョンが決まっていない場合は、推測せずに算出します。

git log v1.3.0..HEAD --oneline | \
  python3 scripts/version_bumper.py --current-version 1.3.0 --output-format json

JSON 出力には、recommended_version、bump_type（major／minor／patch／none）が含まれます。また、--include-commands を指定すると、正確な git tag コマンドも含まれます。recommended_version を generate_changelog.py --next-version に渡してください。プレリリースの場合は、--prerelease alpha|beta|rc を追加します。入力には実際の git log --oneline の出力（16 進数のハッシュ）が必要です。サンプルは assets/sample_git_log.txt にあります。

5. マージ前にコミットをリントする

python3 scripts/commit_linter.py --from-ref origin/main --to-ref HEAD --strict --format text

ファイルまたは stdin を使う場合：

python3 scripts/commit_linter.py --input commits.txt --strict
cat commits.txt | python3 scripts/commit_linter.py --format json

Conventional Commit のルール

サポートされているタイプ：

• feat、fix、perf、refactor、docs、test、build、ci、chore
• security、deprecated、remove

破壊的変更：

• type(scope)!: summary
• フッターまたは本文に BREAKING CHANGE: を含める

SemVer の対応：

• 破壊的変更 -> major
• 破壊的でない feat -> minor
• その他すべて -> patch

スクリプトのインターフェース

• python3 scripts/generate_changelog.py --help
  • Git、stdin、または --input からコミットを読み込む
  • Markdown または JSON をレンダリングする
  • 変更履歴の先頭へのインプレース追加に対応
• python3 scripts/commit_linter.py --help
  • コミット形式を検証する
  • 違反がある場合、--strict モードではゼロ以外の値を返す

よくある落とし穴

1. マージコミットのメッセージをリリース用のコミット解析に混在させる
2. リリースノートにできない曖昧なコミット概要を使う
3. 破壊的変更に対する移行ガイダンスを含め忘れる
4. ドキュメントや雑務の変更をユーザー向け機能として扱う
5. 変更履歴のセクションを先頭に追加せず、過去のセクションを上書きする

ベストプラクティス

1. コミットは小さく、意図が明確なものにします。
2. 複数パッケージのリポジトリでは、コミットメッセージにスコープを付けます（feat(api): ...）。
3. PR パイプラインでリンターチェックを必須にします。
4. 公開前に生成された Markdown を確認します。
5. 変更履歴の生成が成功してからリリースにタグを付けます。
6. 必要に応じて手作業で整理できるよう、[Unreleased] セクションを維持します。

ホットフィックスの重大度と SLA

リリースに問題が発生した場合は、対応前に分類してください（詳しい手順は references/hotfix-procedures.md を参照）。

重大度	定義	SLA	承認者
P0 — 重大	障害、データ損失、悪用された脆弱性	2 時間以内に修正をデプロイ。緊急デプロイでは通常のゲートを迂回	エンジニアリングリード + オンコールマネージャー
P1 — 高	主要機能の障害、大きなユーザー影響	24 時間以内に修正をデプロイ。迅速なレビュー	エンジニアリングリード + プロダクトマネージャー
P2 — 中	軽微な問題、限定的な影響	次のリリースサイクル	通常の PR レビュー

ホットフィックスブランチは最後の安定版タグから作成し、最小限の修正のみを含めます。また、上記のワークフローを使って、独自のパッチバージョン更新用の変更履歴項目を作成します。

ロールバックのトリガー

タグ付け前に以下のしきい値に合意し、いずれかに該当したらロールバックします。

トリガー	しきい値
エラー率の急増	30 分以内にベースラインの 2 倍を超える
パフォーマンスの低下	レイテンシが 50% を超えて増加
機能の障害	コア機能が動作しない
セキュリティインシデント	脆弱性が悪用されている
データの破損	データベースの整合性が損なわれている

コードをロールバックするより、機能フラグを無効にする方法を優先してください。データベースのロールバックは、破壊的でないマイグレーションに限ってください（前方のみのマイグレーションを推奨します）。references/hotfix-procedures.md を参照してください。

参考資料

• references/ci-integration.md
• references/changelog-formatting-guide.md
• references/monorepo-strategy.md
• references/hotfix-procedures.md
• README.md

リリースガバナンス

予測可能なリリースを実現するため、以下のリリースフローを使用してください。

1. 対象リリース範囲のコミット履歴をリントします。
2. コミットから変更履歴のドラフトを生成します。
3. 顧客にわかりやすい表現になるよう、文言を手動で調整します。
4. セマンティックバージョニングによるバージョン更新の推奨内容を検証します。
5. 変更履歴の承認後にのみ、リリースにタグを付けます。

出力品質チェック

• 各箇条書きはユーザーにとって意味があり、実装上のノイズではありません。
• 破壊的変更には移行作業を記載します。
• セキュリティ修正は Security セクションに分けて記載します。
• 項目のないセクションは省略します。
• セクション間の重複する箇条書きは削除します。

CI ポリシー

• すべての PR で commit_linter.py --strict を実行します。
• Conventional Commits の形式に沿っていないコミットがある場合、マージをブロックします。
• タグのプッシュ時にリリースノートのドラフトを自動生成します。
• main ブランチの CHANGELOG.md への書き込み前に、人間による承認を必須とします。

モノレポのガイダンス

• コミットスコープはパッケージ名に合わせることを推奨します。
• パッケージ固有のリリースでは、スコープでコミットの流れを絞り込みます。
• インフラ全体に関わる変更はルートの変更履歴に記載します。
• 所有範囲を明確にするため、パッケージの変更履歴はパッケージのルート付近に保存します。

障害対応

• 有効な Conventional Commits が見つからない場合は、早期に失敗させ、誤解を招く空のリリースノートを生成しません。
• git の範囲が無効な場合は、エラー出力に範囲を明示します。
• 書き込み先が存在しない場合は、安全な変更履歴ヘッダーのひな形を作成します。