prowler-changelog

变更日志条目如何运作：片段

PR 不会直接编辑尚未发布的 CHANGELOG.md 内容；请改用片段。只有已发布区块中的拼写错误或更正可以直接编辑，详情见下文。对于常规条目，请在组件的 changelog.d/ 目录下为每个条目添加一个小型片段文件。发布时，片段会汇总到组件的 CHANGELOG.md 中（并删除已使用的片段），因此并行提交的 PR 不会在变更日志上产生冲突。

组件	片段目录	汇总后的文件
UI	ui/changelog.d/	ui/CHANGELOG.md
API	api/changelog.d/	api/CHANGELOG.md
MCP 服务	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 的各个章节一一对应：

<type>	章节	用途
added	### 🚀 Added	新功能、检查项、端点
changed	### 🔄 Changed	对现有功能的修改
deprecated	### ⚠️ Deprecated	标记为将移除的功能
removed	### ❌ Removed	已删除的功能
fixed	### 🐞 Fixed	Bug 修复
security	### 🔐 Security	安全补丁、CVE 修复

• PR 可根据需要添加任意数量的片段文件，并自由混合类型：每个条目一个文件。例如，修改 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）。
• 每个受影响的组件至少添加一个片段，与旧规则“每个变更日志一个条目”相同。

片段内容

文件中只能包含条目文本，内容应与变更日志中的显示形式完全一致，且位于单独一行，并以换行符结尾：

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 链接。**编译时会自动附加该链接（编译工作流会根据 git 历史找到添加此片段的 PR）。在片段中写入 [(#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：

变更类型	版本递增	示例
Bug 修复、补丁	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 文件之前，Agent 必须停止操作并取得用户的明确确认。即使变更日志关卡未通过、所需文件看似显而易见，或用户要求“修复变更日志”，也必须遵守此要求。

写入前，请先说明拟执行的操作：

1. 目标片段路径（组件、slug、类型）或要编辑的 CHANGELOG.md。
2. 完整的条目文本。
3. 需要添加该变更日志条目的原因。

只有在用户明确批准后（例如“确认”“已批准”“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/ 中添加片段）
多个	每个受影响的组件各添加一个片段

步骤 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）会从 git 历史中解析每个片段对应的 PR，按组件运行编译器，并创建一个 chore(changelog): vX.Y.Z PR（带有 no-changelog 和 skip-sync 标签），将带有版本标记的 ## [X.Y.Z] (Prowler vX.Y.Z) 区块插入每个 CHANGELOG.md，并删除已处理的片段。由人工审核并通过 squash 合并。随后，prepare-release.yml 会像以前一样提取带有版本标记的各个区块。
• 次要版本发布（X.Y.0）： 在切出 v5.X 分支之前，在 master 上编译并合并编译 PR。
• 补丁版本发布（X.Y.Z）： 将修复及其片段文件（无冲突）回合并到 v5.X，在 v5.X 上编译并在那里合并 PR。同一次工作流运行会自动针对 master 创建第二个向前同步 PR（带有 no-changelog 和 skip-sync 标签），在 master 的标记下插入相同的带版本标记区块，并删除已处理的片段，这样下一个次要版本就不会再次发布这些条目；随后应立即合并该 PR。仅存在于 v5.X 上的片段会被跳过，并附带提示。无需手动执行 git 操作。
• 每个区块内的条目按 PR 编号升序排列（大致按时间顺序）。请勿更改此顺序。

修复已发布的条目

已发布版本区块中的 CHANGELOG.md 内容通常不可修改，但对已发布条目进行拼写或内容更正时，PR 可以直接编辑 CHANGELOG.md：进行修改并添加 no-changelog 标签。

如果某个 PR 的条目被放入错误的已发布区块（例如，PR 在发布切分后才合并），请将该条目移回片段：从已发布区块中删除该条目，并将其重新创建为 <component>/changelog.d/<PR>.<type>.md（由于该 PR 会编辑 CHANGELOG.md，请为其添加 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)

---

章节顺序始终为：新增 → 更改 → 弃用 → 移除 → 修复 → 安全。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/