OpenMetadata 贡献者指南基于 PR 模板清单的规范化提交流程【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata导读本篇文章面向 OpenMetadata 仓库的贡献者与代码评审者系统讲解如何利用仓库内置的pr-checklist技能skills/commands/pr-checklist.md 与 skills/pr-checklist/SKILL.md严格依据 .github/pull_request_template.md 的每一节要求收集测试证据、录制 UI 演示、填写完整 PR 描述最终通过gh pr create/gh pr edit创建或更新 Pull Request。读完本文你将掌握一套可复制的 PR 提交流程从git diff变更分类、issue 关联确认、分层测试证据收集到提交前的质量门禁检查每一步都有仓库源码与工作流配置作为依据。一、pr-checklist 技能是什么OpenMetadata 仓库在 skills/pr-checklist/SKILL.md 中定义了一个名为pr-checklist的 AI Agent 技能其作用域非常明确在创建或完善 GitHub PR 之前逐节走查.github/pull_request_template.md模板收集证据并产出一份填写完整的 PR 描述。技能入口声明为skill: openmetadata-skills:pr-checklist可通过 skills/commands/pr-checklist.md 中的命令描述调用。该技能的使用时机来自 skills/pr-checklist/SKILL.md 的 When to Use包括三种场景执行gh pr create之前功能实现完成、提交评审之前更新一个缺少必需章节的既有 PR 描述。命令调用形式支持三个变体参数默认为当前分支相对origin/main的差异/pr-checklist # 针对当前分支 vs origin/main 走查模板 /pr-checklist feature-branch # 针对指定分支走查 /pr-checklist 12345 # 更新既有 PR #12345 的描述二、PR 模板的必需章节技能要求每一个章节都必须被覆盖——确实不适用时用显式的 Not applicable — 说明理由而不是留空。六个必需章节及其在 .github/pull_request_template.md 中的位置如下#章节模板要求1Linked issueFixes #issue-numberGitHub 自动关联没有 issue 必须先创建2Type of change恰好勾选一个类型框3High-level design大型 PR新功能、重构、破坏性变更、5 个文件必填小型 bug 修复可跳过4Tests覆盖用例、单元测试 覆盖率、后端集成测试、ingestion 集成测试、PlaywrightUI测试、手工测试步骤5UI screen recording / screenshots任何 UI 变更都强制要求6Checklist每个勾选框要么勾上要么显式标注 N/A模板中Type of change的可选项为Bug fix、Improvement、New feature、Breaking change、Documentation——模板注释明确要求「choose 1 option and delete options that arent relevant」即恰好勾选一项避免 PR 类型含混。三、七步工作流详解Step 1 — 检查变更范围并对 PR 分类第一步通过三条命令获取变更概览git status git diff origin/main...HEAD --stat git log origin/main..HEAD --oneline然后依据 diff 结果对 PR 进行分层分类这决定了后续需要收集哪几类证据触及openmetadata-ui/src/main/resources/ui/→UI 变更强制要求录制视频触及openmetadata-service/且新增/修改 REST 端点 →必须补后端集成测试触及ingestion/src/metadata/ingestion/source/→必须补 ingestion 测试变更文件 5 个或属于新功能 / 重构 / 破坏性变更 →必须写 high-level design单文件修复且影响范围明确 → 属于小型变更design 章节可写N/A。Step 2 — 确认关联 issue分支名或提交信息通常能提示 issue 编号若不明显需向用户确认。用如下命令验证 issue 真实存在gh issue view issue-number如果不存在对应 issue立即停止并要求用户先创建 issue 再继续。这一步并非只是流程形式——仓库在 .github/workflows/pr-metadata-validation.yml 中运行了一个名为 PR Metadata Validation 的工作流它通过 GraphQL 查询 PR 的closingIssuesReferences同一仓库的权威来源来校验 PR 是否真正链接了 issue并要求该 issue 拥有至少 25 个词的实质描述且已加入 Shipping 项目并设置了Status、Source、Priority、Domain、Release五个字段否则 PR 检查直接失败。跨仓库同组织内的 issue 链接则从 PR 正文按Fixes open-metadata/repo#123格式解析且仅对受信任作者与显式白名单仓库生效见工作流中的ALLOWED_CROSS_REPOS与TRUSTED_ASSOCIATIONS策略。Step 3 — 收集分层测试证据技能反复强调不要编造覆盖率数字去实际运行工具并记录输出。四层测试的命令如下。后端Java单元测试与覆盖率mvn test -pl openmetadata-service -DtestChangedTestClass mvn jacoco:report -pl openmetadata-service # 覆盖率 HTML 报告: openmetadata-service/target/site/jacoco/index.html后端集成测试mvn test -pl openmetadata-integration-tests -DtestNewITIngestionPython单元测试source env/bin/activate cd ingestion make unit_ingestion_dev_env python -m pytest tests/unit/changed_path/ --covmetadata.module --cov-reportterm-missing其中make unit_ingestion_dev_env定义在 ingestion/Makefile注释明确其用途为 Run Python unit tests except some specific ones. Only for local development!即本地开发用的精简版单元测试目标。前端单元测试Jestcd openmetadata-ui/src/main/resources/ui yarn test ChangedComponent --coverageyarn test:coverage脚本在 openmetadata-ui/src/main/resources/ui/package.json 中定义为jest --passWithNoTests --coverage。PlaywrightUI E2Ecd openmetadata-ui/src/main/resources/ui yarn playwright:run --grep feature name同样playwright:run在 package.json 中映射为playwright test而 Playwright 测试实际位于 openmetadata-ui/src/main/resources/ui/playwright/e2e按Auth、Features、Flow、Pages、Search、VisualRegression等目录组织。技能还给出一个提效建议这些证据收集工作可以直接交给仓库内另一个技能/test-enforcement完成——它产出一致的证据并强制变更类 90% 的行覆盖率参见 skills/test-enforcement/SKILL.md其中明确了各层覆盖率目标openmetadata-service用 JaCoCo 达成 90% 行覆盖、API 端点 100% 覆盖、Playwright 覆盖所有新增用户流程、Python ingestion 90% 行覆盖。如果用户尚未运行它建议优先运行。Step 4 — 收集手工测试步骤向用户确认「你手动做了什么来验证它可用」并将步骤整理为具体、可复现的清单例如启动本地栈./docker/run_local_docker.sh -m ui -d mysql该脚本存在于 docker/run_local_docker.sh登录的用户 / 角色在 UI 中点击的路径样例输入与观察到的输出负向路径检查错误场景、权限拒绝。Step 5 — UI 屏幕录制仅 UI 变更PR 触及 UI 时录制是强制要求macOS 自带CmdShift5→ Record Selected Portion保存为.mov直接拖拽进 PR 描述GitHub 会上传为内联附件视觉变化工具栏、布局、配色需同时附带 before/after 截图。若用户暂时无法附加录制把该章节标记为TODO: attach recording不要直接打开 PR——要么等录制补齐要么以 draft 形式打开。Step 6 — 起草 PR 描述用上面收集到的全部信息填写 .github/pull_request_template.md。注意模板的语义细节标题行固定格式Fixes issue-number: short explanationHigh-level design章节对大型 PR 要求覆盖采取的架构/方案及原因、新增/变更的关键组件及交互、考虑过并否决的替代方案、迁移/向后兼容/发布关注点、可用的图表或设计文档链接Tests章节按Use cases covered、Unit tests、Backend integration tests、Ingestion integration tests、Playwright (UI) tests、Manual testing performed六块填写每块要么列出实际文件与覆盖率数字要么勾选 Not applicable模板还按变更类型Bug fix / Improvement / New feature / Breaking change提供了不同的补充清单例如破坏性变更需添加Backward-Incompatible-Change标签。创建前先把完整草稿展示给用户评审。Step 7 — 创建或更新 PR新建 PR用 HEREDOC 保证格式不被 shell 破坏gh pr create --base main --title Fixes #issue: short title --body $(cat EOF filled-in template here EOF )更新既有 PRgh pr edit number --body $(cat EOF filled-in template here EOF )完成后返回 PR 的 URL。四、创建 PR 前的质量门禁技能明确要求以下任一项缺失就拒绝打开 PR改为把这些缺口反馈给用户关联 issue 存在并以Fixes #N形式引用PR 标题符合Fixes issue-number: short explanation格式至少勾选一个 Type of change 框大型 PR 的 high-level design 章节已填写非N/ATests 章节列出了实际文件和覆盖率数字非占位符UI 变更已附加屏幕录制或标记 TODO 并以 draft 打开 PR手工测试步骤具体且可复现针对变更类型的跨层检查通过如make generate、mvn spotless:apply、yarn lint等。这些门禁与仓库 CI 是互为印证的关系除前面提到的 .github/workflows/pr-metadata-validation.yml 外仓库还维护了java-checkstyle.yml、ui-checkstyle.yml、py-checkstyle.yml、yarn-coverage.yml、java-playwright-nightly.yml等一整套工作流见 .github/workflows在 CI 侧强制执行风格与测试门禁而 pr-checklist 技能则在提交前帮助贡献者在本地先把关。五、常见的遗漏点与规避方法技能最后列出了社区评审中反复出现的六类典型问题贡献者应主动对照自查Schema 变更未运行make generate→ 生成的模型与 schema 脱同步后端 API 变更未在openmetadata-integration-tests/补集成测试→ 端点缺少回归保障新 UI 功能缺少 Playwright spec→ 用户流程无人值守验证Bug 修复没有回归测试→ 应补一个在修复前会失败的测试来锁定行为大型重构在 design 章节写N/A→ 应驳回并要求补充设计说明从别的 PR 复制粘贴覆盖率数字→ 必须重新运行工具获取真实数值。这六点共同指向一个原则PR 描述不是形式主义而是让评审者与 CI 都能快速验证「改了什么、为什么改、如何证明它对」。结语OpenMetadata 的pr-checklist技能把仓库 PR 模板的要求拆解成了一条可执行的流水线变更分类 → issue 确认 → 分层测试证据 → 手工验证步骤 → UI 录制 → 草稿评审 → 创建/更新 PR。配合 .github/pull_request_template.md 的六节结构与 .github/workflows/pr-metadata-validation.yml 的自动校验贡献者可以在提交前就完成大部分质量把关让评审聚焦于真正的技术决策而非流程补漏。无论是首次贡献者还是资深 reviewer都可以把这套清单作为提交 OpenMetadata PR 的默认工作流。【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考