Prowler 开源仓库 Pull Request 提交规范与实战指南：模板、Conventional Commits 与 CI 门禁全解析-开发者社区

Prowler 开源仓库 Pull Request 提交规范与实战指南：模板、Conventional Commits 与 CI 门禁全解析

【免费下载链接】prowlerProwler is the world’s most widely used open-source cloud security platform that automates security and compliance across any cloud environment.项目地址: https://gitcode.com/GitHub_Trending/pr/prowler

本篇指南基于 Prowler 仓库内置的 AI 技能文档 skills/prowler-pr/SKILL.md，系统讲解在 Prowler 多组件 monorepo（SDK、API、UI、MCP Server）中创建高质量 Pull Request 的完整流程：从分析变更、按模板填充、遵循 Conventional Commits 标题约定，到通过 changelog 门禁、冲突检查与代码评审再请求机制。读完本文，你将能够用ghCLI 与 git 命令，一次通过 CI 校验地提交符合项目规范的 PR。

PR 创建流程总览

skills/prowler-pr/SKILL.md将 PR 创建归纳为四步核心流程，配合仓库中的真实 CI 工作流，构成一条从本地分支到合并的完整链路：

分析变更：执行git diff main...HEAD理解分支上相对main的全部提交内容；
确定受影响组件：判断变更落在 SDK（prowler/）、API（api/）、UI（ui/）、MCP（mcp_server/）还是 Docs（docs/），这一步直接决定 changelog 碎片文件写到哪里；
按模板填充各小节：以 .github/pull_request_template.md 为骨架填写 Context、Description、Steps to review、Checklist；
创建 PR：使用gh pr create提交，标题遵循 Conventional Commits 约定。

仓库的pr-conflict-checker.yml与pr-check-changelog.yml会在 PR 创建后自动接管校验，因此第 1、2 步做得越细致，后续被 CI 打回重做的概率越低。

理解 Prowler 的多组件结构

Prowler 是一个包含多个独立交付组件的仓库，每个组件有自己独立的目录、CHANGELOG.md与changelog.d/碎片目录（见下表，源自 SKILL.md 与 skills/prowler-changelog/SKILL.md 的交叉验证）：

组件	源码目录	Changelog 碎片目录	编译产物
SDK/CLI	`prowler/`	`prowler/changelog.d/`	`prowler/CHANGELOG.md`
API	`api/`	`api/changelog.d/`	`api/CHANGELOG.md`
UI	`ui/`	`ui/changelog.d/`	`ui/CHANGELOG.md`
MCP Server	`mcp_server/`	`mcp_server/changelog.d/`	`mcp_server/CHANGELOG.md`

从源码结构看，仓库根目录的uv.lock与pyproject.toml被归入 SDK 组件——pr-check-changelog.yml中明确将这两个根级依赖文件与prowler/changelog.d/碎片绑定（见 .github/workflows/pr-check-changelog.yml 中root_deps_changed逻辑）。

PR 模板结构：每个小节该写什么

PR 模板的实际文件位于 .github/pull_request_template.md，SKILL.md 与之一致。创建 PR 时必须完整填充以下小节：

Context

写清楚为什么做这个变更（动机与背景），若该 PR 修复某个 issue，使用Fix #XXXX语法建立 issue↔PR 关联。仓库的 changelog 编译规则规定，编译产物中的条目只允许带 PR 链接，issue 与 PR 的映射关系正是通过这里的Fixes #N完成的。

Description

总结变更内容与所依赖的其它改动（dependencies）。要点是"改了什么"，而不是"为什么改"——动机属于 Context。

Steps to review

给出审阅者如何验证此变更的具体步骤：复现路径、测试命令、预期行为等，帮助 reviewer 快速进入状态。

Checklist

模板清单分为两层：可折叠的Community Checklist与按组件展开的检查项。完整内容（源自 .github/pull_request_template.md）：

### Checklist <details> <summary><b>Community Checklist</b></summary> - [ ] 该 feature/issue 是否已列在项目的 open issues 或 roadmap 中 - [ ] 是否已分配给本人，若未分配，请通过 issue/feature 渠道或社区 Slack 申请 - [ ] 已检查 open pull requests，确认没有已存在的 PR 实现相同结果 </details> - [ ] 检查代码是否有测试覆盖 - [ ] 检查代码是否遵循 Google Python Style Guide 的注释与 Docstring 规范 - [ ] 检查是否需要 backport（回溯到维护分支） - [ ] 检查是否需要修改 README.md - [ ] 如适用，确保在 <组件>/changelog.d/ 下添加 changelog 碎片

SDK/CLI 专属：PR 是否包含新检查（check）？若是，是否需要为对应云厂商更新权限（permissions）——SKILL.md 特别强调"请仔细审查此项"。权限模板位于 permissions/ 目录，例如 AWS 的prowler-additions-policy.json与 Azure 的prowler-azure-custom-role.json。

UI 专属（如适用）：

- [ ] 所有 issue/任务需求在 UI 上按预期工作 - [ ] 若新增或更新 npm 依赖，附上包健康度证据（维护状况、流行度、已知漏洞、许可证、发布年龄）并说明为何现有/原生方案不足 - [ ] 功能流程截图/视频 - Mobile (X < 640px) - [ ] 功能流程截图/视频 - Tablet (640px > X < 1024px) - [ ] 功能流程截图/视频 - Desktop (X > 1024px) - [ ] 确保在 ui/changelog.d/ 下添加 changelog 碎片

API 专属（如适用）：

- [ ] 所有 issue/任务需求在 API 上按预期工作 - [ ] 端点响应输出（如适用） - [ ] 新增/修改的查询或索引的 EXPLAIN ANALYZE 输出（如适用） - [ ] 性能测试结果（如适用） - [ ] 其它相关实现证据（如适用） - [ ] 验证是否需要重新生成 API specs - [ ] 检查是否需要版本更新（如 specs、uv 等） - [ ] 确保在 api/changelog.d/ 下添加 changelog 碎片

MCP Server 专属：

- [ ] 所有 issue/任务需求在 MCP Server 上按预期工作 - [ ] 确保在 mcp_server/changelog.d/ 下添加 changelog 碎片

License

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

组件特定规则速查

SKILL.md 给出了按组件区分的额外检查点，与模板中的组件小节一一对应：

组件	Changelog 碎片目录	额外检查
SDK	`prowler/changelog.d/`	新增检查 → 是否需要更新云厂商权限？
API	`api/changelog.d/`	API specs、版本升级、端点输出、EXPLAIN ANALYZE、性能测试
UI	`ui/changelog.d/`	Mobile/Tablet/Desktop 三端截图
MCP	`mcp_server/changelog.d/`	无额外要求

创建 PR 的完整命令集

SKILL.md 提供了从分支检查到创建 PR 的完整命令链：

# 检查当前分支状态 git status git log main..HEAD --oneline # 查看完整差异 git diff main...HEAD # 用 heredoc 填充正文创建 PR gh pr create --title "feat: description" --body "$(cat <<'EOF' ### Context ... EOF )" # 创建草稿 PR gh pr create --draft --title "feat: description"

其中git diff main...HEAD的三点语法表示对比main与当前分支的共同祖先到当前分支的差异，确保只展示本分支独有的变更——这与 SKILL.md "分析 main...HEAD 以理解全部提交" 的要求一致。

标题约定：Conventional Commits

SKILL.md 要求 PR 标题遵循 Conventional Commits 规范，允许的前缀为：

feat:新功能
fix:缺陷修复
docs:文档
chore:维护
refactor:代码重构
test:测试

这一约定并非软性建议，而是被 CI 强制执行。在 .github/workflows/conventional-commit.yml 中，agenthunt/conventional-commit-checker-action使用如下正则校验 PR 标题：

^(feat|fix|docs|style|refactor|perf|test|chore|build|ci|revert)(\([^)]+\))?!?: .+

这意味着：

前缀取自feat|fix|docs|style|refactor|perf|test|chore|build|ci|revert之一（比 SKILL.md 列的六类更全，还包含style、perf、build、ci、revert）；
可选的(scope)作用域，如feat(aws): ...；
可选的!表示破坏性变更；
前缀与描述之间必须用:（冒号加空格）分隔，描述不能为空。

该工作流仅在 PR 目标分支为master或v5.*时触发，事件类型为opened、edited、synchronize——也就是说，修改 PR 标题也会重新触发检查。参考仓库中的真实示例，changelog 编译 PR 使用chore(changelog): vX.Y.Z这样的标题。

Changelog 门禁：pr-check-changelog 工作流

PR 的 changelog 要求由 .github/workflows/pr-check-changelog.yml 强制执行，规则如下（与 SKILL.md 一致）：

必需：触及ui/、api/、mcp_server/、prowler/任一目录的 PR，必须在对应changelog.d/下新增（或修复）碎片文件；
文件名校验：碎片文件名必须匹配正则^[A-Za-z0-9][A-Za-z0-9._-]*\.(added|changed|deprecated|removed|fixed|security)(\.[0-9]+)?\.md$，类型取值与 keepachangelog 章节一一对应：added、changed、deprecated、removed、fixed、security；
内容 lint：碎片内容中禁止手写 PR 或 issue 链接（匹配[(#N)]、#N或github.com/.../(pull|issues)/N都会被拒绝），因为链接会在发布编译时由 git 历史自动解析附加；
禁用直接编辑：常规 PR 直接修改CHANGELOG.md会被拒绝——只有已发布版本的拼写修正等例外场景允许，且需加no-changelog标签；
跳过：添加no-changelog标签可跳过校验（仅限纯文档、纯 CI 变更等场景，需谨慎使用）。

工作流还会自动在 PR 上发布/更新一条状态注释（标记），并在缺失或非法时以exit 1使检查失败。碎片文件的正确创建方式（见 skills/prowler-changelog/SKILL.md）：

echo '条目文本，描述这次变更' > <组件>/changelog.d/<slug>.<type>.md

例如新增 AWS Security Hub 检查：

echo '`securityhub_delegated_admin_enabled_all_regions` check for AWS provider' > prowler/changelog.d/securityhub-delegated-admin.added.md

碎片正文规则：只写条目文本、单行、结尾换行、句末不加句号、不要以冗余动词开头（章节标题已提供动作语义）、不要写 PR 链接。判定受影响组件的辅助命令：

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

一个 PR 可以按需添加多个碎片（每个条目一个文件），例如同时包含kms-rotation-check.added.md与kms-disabled-keys.fixed.md；同一类型多条时使用不同 slug 区分。

其它配套 PR 检查工作流

除 changelog 门禁外，仓库还为 PR 配置了多个自动化检查（均可从 .github/workflows/ 查看）：

冲突检查（pr-conflict-checker.yml）：检出 PR head SHA，扫描所有变更文件中是否残留冲突标记（conflict markers），避免带着未解决的 merge conflict 提交；
自动打标（labeler.yml）：基于变更文件自动应用标签，并为社区贡献者（非组织成员）的首次 PR 添加community标签；
评审所有权（CODEOWNERS）：.github/、Makefile、kubernetes/、所有Dockerfile与docker-compose*归@prowler-cloud/platform；SDK（/prowler/、/tests/、/dashboard/、/docs/等）、API、UI、MCP 均归@prowler-cloud/engineering——提交 PR 前可以据此预判会被哪个团队 review；
此外还有sdk-tests.yml、api-tests.yml、ui-tests.yml、ui-e2e-tests-v2.yml等组件测试与安全扫描工作流，共同构成 PR 的完整质量闸门。

创建 PR 前的五步自检

SKILL.md 要求创建 PR 前逐一确认：

✅ 本地全部测试通过：SDK 使用make test（pytest -n auto -vvv -s --cov=./prowler --cov-report=xml tests，见 Makefile），MCP 使用make test-mcp；
✅ Lint 通过：make lint一键执行全部组件 lint（SDK 走flake8+black --check+pylint，API 与 MCP 走ruff check+ruff format --check，与 CI 完全一致）；
✅ 已添加 changelog 碎片（如适用，见上文门禁规则）；
✅ 分支已与main保持同步；
✅ 提交信息干净、具有描述性。

make lint的实现细节（源自 Makefile 第 61-85 行）：lint是lint-sdk、lint-api、lint-mcp的组合目标，其中 SDK 组件通过uv run执行 flake8（忽略E266,W503,E203,E501,W605,E128）、black 检查与 pylint，API/MCP 各自在组件目录内执行 ruff 检查与格式校验。

重新请求 Review 前：处理评审线程（必需）

SKILL.md 特别强调：在重新请求 review 之前，必须解决或回应每一条未关闭的 inline review 线程，这是强制要求而非建议：

同意并已修复：提交修复，并以 commit hash 回复审阅者，便于快速验证，例如：Fixed in abc1234.；
同意但延后：说明为何超出本 PR 范围，以及记录在哪里跟踪；
不同意：给出清晰的技术理由进行回复，不允许让线程静默悬挂；
重新请求 review：仅在所有线程处于干净状态（已解决或已明确回应）之后进行。

经验法则（源自 SKILL.md）：审阅者重新打开 PR 时，绝不应该产生"他们到底看没看到我的评论？"的疑问。

总结

Prowler 的 PR 提交流程是一套"模板 + 约定 + CI 门禁"三位一体的工程实践：模板（.github/pull_request_template.md）保证信息完整，Conventional Commits（conventional-commit.yml）统一标题语义，changelog 碎片机制（pr-check-changelog.yml + skills/prowler-changelog/SKILL.md）让并发 PR 互不冲突，CODEOWNERS与多工作流则自动分配评审责任。按照本文的流程操作，即可提交一份结构完整、一次通过 CI 校验、便于评审的高质量 PR。更多 PR 约定与流程细节，可参考仓库的开发者指南 docs/developer-guide/introduction.mdx（"Sending the Pull Request" 章节）以及 skills/prowler-pr/references/pr-docs.md。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考