keep-a-changelog

Keep a Changelog アシスタント

変更履歴は人が読むためのものです。優れた変更履歴なら、差分を読まなくても「アップグレードすると何が変わるのか」を把握できます。エージェントは ## [Unreleased] を管理し、明示的に依頼された場合はバージョンセクションを準備します。いつリリースを作成し、タグを付け、公開するかは人が決めます。

形式、カテゴリ、破壊的変更、リバート、取り下げられたリリース、エントリーの書き方、このリポジトリ固有のルール、および2つのワークフローについては、references/spec-and-workflows.md を参照してください。ファイルを編集する前に読み込んでください。scripts/validate_changelog.py は、そのうち機械的に検証できる項目をチェックします。

python3 skills/keep-a-changelog/scripts/validate_changelog.py CHANGELOG.md
python3 skills/keep-a-changelog/scripts/validate_changelog.py --house-rules CHANGELOG.md

このスクリプトは編集を行いません。以下に述べるすべての内容を判断できるわけではありません。

エントリーに含める変更

利用者にとって意味のある変更だけを含めます。判断基準は、ユーザーがソフトウェアをインストール、インポート、使用する方法、またはソフトウェアを信頼すべきかどうかに影響するかです。そうでなければ、リリースで最も大きな変更であっても記載しません。

通常、含めるもの：公開 API の変更、新規または変更された動作、パッケージングやインストールの変更、非推奨化、セキュリティ修正。

通常、含めないもの：テストの変更、CI やワークフローの更新、内部ツール、ドキュメントのみの変更、フォーマットやリンターのみの変更、外から見える影響のないリファクタリング、些細な名前変更。

リポジトリ独自の構成から、製品コードの境界を読み取ってください。出荷されるコードが置かれている場所（src/、cmd/ と internal/、lib/、またはパッケージディレクトリなど）を確認し、その中の変更をユーザーに関係するものとして扱います。対象には公開 API やコマンド、ドメインプリミティブ、コントラクトやスキーマ、動作、パッケージングが含まれます。あるリポジトリの境界を別のリポジトリにそのまま当てはめないでください。

バリデーターが決して判断できないことが2つあります。

• 変更が2つのカテゴリに当てはまる場合、どのカテゴリが主となるか。 バグも修正する書き換えの場合、主題が書き換えなら Changed、修正なら Fixed にします。両方に記載すると、リリースの規模が実際の2倍に見えてしまいます。
• エントリーが事実に即しており、結果を示す内容になっているか。 実装の説明になっていて効果を説明していないエントリーは、形式が整っていればすべてのチェックに合格しますが、それでも読者の期待には応えられません。

破壊的変更としてマークされたコミット（💥 / ! / BREAKING CHANGE: フッター。gitmoji-conventional を参照）ごとに、変更内容を明記したエントリーを作成し、次のリリースが MAJOR になることを示してください。

関連スキル

• gitmoji-conventional — コミットメッセージと PR タイトルに関するスキルです。破壊的変更のマーカーは、エントリーでその変更を明記すべきことを示します。マーカーがない場合は、差分から同じ兆候を読み取ってください。公開シンボルの削除や変更は、コミットの件名にかかわらず破壊的変更です。