prowler-changelog

変更履歴エントリーの仕組み：フラグメント

PR では、未リリースの CHANGELOG.md の内容を直接編集しません。代わりにフラグメントを使用してください。リリース済みブロックの誤字や記述の修正のみ、直接編集の例外として認められます。詳細は以下をご覧ください。通常のエントリーでは、コンポーネントの changelog.d/ ディレクトリに、エントリーごとに小さなフラグメントファイルを1つ追加します。フラグメントはリリース時にコンポーネントの CHANGELOG.md にまとめられます（使用済みのフラグメントは削除されます）。そのため、複数の PR が変更履歴で競合することはありません。

コンポーネント	フラグメントディレクトリ	生成されるファイル
UI	ui/changelog.d/	ui/CHANGELOG.md
API	api/changelog.d/	api/CHANGELOG.md
MCP Server	mcp_server/changelog.d/	mcp_server/CHANGELOG.md
SDK	prowler/changelog.d/	prowler/CHANGELOG.md

「未リリースの内容」とは「changelog.d/ にある内容」です。生成される CHANGELOG.md ファイルには、リリース済みのバージョンのみが記載されます。

フラグメントのファイル名

<slug>.<type>.md

• <slug> は自由に指定できます（[A-Za-z0-9][A-Za-z0-9._-]*）。作成者が選び、変更内容がわかる名前にするのが理想的です（例：securityhub-delegated-admin）。PR 番号がすでにわかっている場合は、それを slug に使うこともできます（例：11259）。必須ではありません。
• <type> は keepachangelog のセクションに1対1で対応します。

<type>	セクション	用途
added	### 🚀 Added	新機能、チェック、エンドポイント
changed	### 🔄 Changed	既存機能の変更
deprecated	### ⚠️ Deprecated	削除予定としてマークされた機能
removed	### ❌ Removed	削除された機能
fixed	### 🐞 Fixed	バグ修正
security	### 🔐 Security	セキュリティパッチ、CVE の修正

• PR では、必要なエントリーの数だけフラグメントファイルを追加でき、タイプも自由に組み合わせられます。つまり、エントリーごとに1ファイルです。たとえば、Added、Changed、Fixed にまたがる変更を含む PR では、kms-rotation-check.added.md + kms-metadata-cache.changed.md + kms-disabled-keys.fixed.md を追加します。すべて同じ PR リンクとともに、それぞれのセクションにまとめられます。
• 同じタイプのエントリーが複数ある場合は、エントリーごとに異なる slug を使います（kms-rotation-check.added.md、kms-rotation-docs.added.md）。
• 変更を加えた各コンポーネントに、少なくとも1つのフラグメントが必要です。これは、変更履歴ごとに1エントリーとしていた従来のルールと同じです。

フラグメントの内容

ファイルには、変更履歴に記載するエントリーテキストのみを、末尾に改行を付けて1行で記述します。

echo '`securityhub_delegated_admin_enabled_all_regions` check for AWS provider, verifying that Security Hub has a delegated administrator, is active in all opted-in regions, and has organization auto-enable on' > prowler/changelog.d/securityhub-delegated-admin.added.md

ルール（従来どおりの文章表記規則）：

• PR リンクをテキストに記載しないでください。 リンクはコンパイル時に自動で追加されます（コンパイルのワークフローで、フラグメントを追加した PR が git の履歴から特定されます）。フラグメントに [(#NNNN)](...) を記載すると、リンクが重複します。
• 文末にピリオドを付けない
• 冗長な動詞で書き始めない（セクション見出しにすでに変更内容が示されています）
• 変更の理由ではなく、変更内容を具体的に記載する（理由は PR に記載します）
• 読みやすいエントリーにする：インラインコードや製品名の前後にはスペースを入れ、エンドポイント、コマンド、エラー、タスク名、ファイルパスはバッククォートで囲む
• 長く続く文は避ける。複雑な変更は、簡潔な結果と簡潔な補足説明に分ける

良いフラグメント

# ui/changelog.d/provider-search-bar.added.md
Search bar when adding a provider

# api/changelog.d/scan-dispatch-race.fixed.md
`POST /api/v1/scans` no longer intermittently fails with `Scan matching query does not exist`; scan dispatch now publishes the `scan-perform` Celery task after the transaction commits

# ui/changelog.d/node-24-bump.security.md
Node.js from 20.x to 24.13.0 LTS, patching 8 CVEs

悪いフラグメント

Fixed bug.                              # Too vague, has period, redundant verb
Add search bar                          # Redundant verb (the section already says "Added")
Search bar [(#9634)](https://github.com/prowler-cloud/prowler/pull/9634)   # NEVER include the PR link; it is added at compile time

セマンティックバージョニングのルール

Prowler は semver.org に従います。

変更の種類	バージョンの更新	例
バグ修正、パッチ	PATCH (x.y.Z)	1.16.1 → 1.16.2
新機能（後方互換性あり）	MINOR (x.Y.0)	1.16.2 → 1.17.0
破壊的変更、削除	MAJOR (X.0.0)	1.17.0 → 2.0.0

重要： removed フラグメントは、必ず MAJOR バージョンのリリースにのみ含めてください。機能の削除は破壊的変更です。

必須の人間による確認ゲート

変更履歴の断片または CHANGELOG.md ファイルを作成または編集する前に、エージェントは必ず作業を中断し、ユーザーから明示的な確認を得る必要があります。変更履歴ゲートが失敗している場合、必要なファイルが明らかに思える場合、またはユーザーが「変更履歴を修正して」と依頼した場合も同様です。

書き込みを行う前に、次の作業案を提示してください。

1. 対象となる断片のパス（コンポーネント、スラッグ、種類）または CHANGELOG.md の編集内容。
2. 正確なエントリーテキスト。
3. 変更履歴エントリーが必要な理由。

「confirm」、「approved」、「sí」など、明示的な承認を得てから作業を進めてください。ユーザーが拒否した場合、または回答がない場合は、何も作成・編集しないでください。適切な場合は、代替案として no-changelog の追加などを提案してください。

変更履歴エントリーの追加

ステップ 1：影響を受けるコンポーネントを特定する

git diff master...HEAD --name-only | grep -E '^(ui|api|mcp_server|prowler)/' | cut -d/ -f1 | sort -u

パスのパターン	コンポーネント
ui/**	UI
api/**	API
mcp_server/**	MCP Server
prowler/**	SDK
ルートの uv.lock / pyproject.toml	SDK（ゲートでは prowler/changelog.d/ の断片が必要です）
複数	影響を受けるコンポーネントごとに 1 つの断片

ステップ 2：断片を作成する

echo 'Entry text describing the change' > <component>/changelog.d/<slug>.<type>.md

ステップ 3：保留中の断片を確認する

ls prowler/changelog.d/ api/changelog.d/ ui/changelog.d/ mcp_server/changelog.d/

PR 変更履歴ゲート

pr-check-changelog.yml ワークフローによって、断片の追加が必須になります。

1. 必須：ui/、api/、mcp_server/、または prowler/ に変更を加える PR では、対応する changelog.d/ の下に断片を追加（または修正）する必要があります。
2. 検証：追加する断片のファイル名は、妥当な種類を使った <slug>.<type>.md 形式である必要があります。
3. リント：断片の内容に、手書きの PR リンク（[(#N)](...)）を含めてはいけません。リンクはコンパイル時に自動で付与されるため、見つかった場合はゲートが失敗します。
4. スキップ：回避するには no-changelog ラベルを追加します（ドキュメントのみ、CI のみの変更などに限り、慎重に使用してください）。

リリースフロー（コンパイル）

• リリース時に、compile-changelogs ワークフロー（手動実行：prowler_version + target_branch。コンポーネントごとのバージョンは Prowler のバージョンに合わせて自動算出されます。SDK は同じバージョン、UI は 1.<minor>.<patch>、API は 1.<minor + 1>.<patch> となり、MCP Server のみ保留中の断片の種類に基づいて算出されます。明示的な上書きまたは skip も指定できます）が、各断片に対応する PR を Git の履歴から特定し、コンポーネントごとにコンパイラーを実行して、chore(changelog): vX.Y.Z PR を作成します。この PR には no-changelog と skip-sync のラベルが付き、各 CHANGELOG.md にスタンプ付きの ## [X.Y.Z] (Prowler vX.Y.Z) ブロックを挿入し、使用済みの断片を削除します。人間がレビューし、スカッシュマージします。その後、prepare-release.yml がこれまでと同様にスタンプ付きセクションを抽出します。
• マイナーリリース（X.Y.0）： master でコンパイルし、v5.X ブランチを切る前にコンパイル PR をマージします。
• パッチリリース（X.Y.Z）： 修正を断片ファイルとともに v5.X にバックポートします（コンフリクトがないこと）。v5.X でコンパイルし、その PR を同ブランチでマージします。同じワークフローの実行によって、master のマーカーの下に同じスタンプ付きブロックを挿入し、使用済みの断片を削除する 2 つ目のフォワード同期 PR が master に対して自動的に作成されます。この PR には no-changelog と skip-sync のラベルが付き、次のマイナーリリースで同じエントリーが再リリースされないようにします。続けてすぐにマージしてください。v5.X にしか存在しなかった断片は通知付きでスキップされます。手動での Git 操作は不要です。
• セクション内のエントリーは PR 番号の昇順（おおむね時系列順）で並びます。この順序を変更しないでください。

リリース済みエントリーの修正

リリース済みバージョンの CHANGELOG.md ブロックは、通常は変更できません。ただし、リリース済みエントリーの誤字や訂正の修正は例外であり、この場合に限り、PR で CHANGELOG.md を直接編集できます。編集を行い、no-changelog ラベルを追加してください。

PR のエントリーが誤ったリリース済みブロックに含まれている場合（例：リリースが確定した後に PR がマージされた場合）、エントリーを断片に戻してください。リリース済みブロックから削除し、<component>/changelog.d/<PR>.<type>.md として再作成します（CHANGELOG.md を編集するため、PR に no-changelog ラベルを付けてください）。

コンパイル後の CHANGELOG.md の形式（参考）

コンパイラーはリリースごとに、各 CHANGELOG.md の `` マーカーのすぐ下に次の内容を出力します（このマーカーは絶対に削除しないでください）。

## [X.Y.Z] (Prowler vA.B.C)

### 🚀 Added

- Entry text [(#NNNN)](https://github.com/prowler-cloud/prowler/pull/NNNN)

### 🐞 Fixed

- Fix entry [(#NNNN)](https://github.com/prowler-cloud/prowler/pull/NNNN)

---

セクションの順序は常に次のとおりです：Added → Changed → Deprecated → Removed → Fixed → Security。X.Y.Z はコンポーネントのバージョン、A.B.C は Prowler のリリースバージョンです。各エントリーの末尾には必ず PR へのリンクを付けてください。/issues/N へのリンクは禁止です。Issue と PR の対応関係は、PR の本文に Fixes #N と記載します。

リソース

• テンプレート：エントリーのテンプレートは assets/ を参照してください
• keepachangelog.com：https://keepachangelog.com/en/1.1.0/