Novu 提交 PR 前的工程化自查指南从特性分支到 Merge-Ready 的九步工作流【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu导读在 Novu 开源 monorepo工作区apps/、libs/、packages/、enterprise/并存中一个功能分支从“代码写完”到“PR 可合并”中间隔着质量审查、安全排查、本地验证、CI 排障与评审回复等一连串工程步骤。本文以仓库内 .cursor/skills/novu-prepare-pr/SKILL.md 描述的PR 准备Prepare PR工作流为主体结合仓库真实的构建命令、PR 规范与安全代码样例讲解如何在功能实现完成之后系统化地完成范围校验、质量过检、提交规整、PR 创建与合并前检查。读完本文你将掌握一套可直接套用在 Novu 代码库上的 PR 就绪流程并理解其中每条检查项背后的仓库实现依据。一、这套流程解决什么问题Novu 的工程实践是“先实现、后提 PR”而这套novu-prepare-prskill 正是用来衔接“实现完成”与“合并上线”的收尾工序。它只应在特性分支上功能实现已结束后运行其边界约束很清晰见 SKILL.md不做重新规划、不扩大范围除非 review 或 CI 暴露了真实的缺口前置条件是功能代码已在一个分支上仓库约定习惯使用cursor/short-description从next分支切出分支名能对应到 Linear 工单编号nv-XXXX/NV-XXXX或可根据工单推断编号。整套流程收敛为一份可勾选的进度清单共 9 步PR prep progress: - [ ] 1. Scope diff sanity - [ ] 2. Quality passes - [ ] 3. Security check (if shared/multi-tenant) - [ ] 4. Local validation - [ ] 5. Commit hygiene - [ ] 6. Open or update PR - [ ] 7. CI triage fix - [ ] 8. Review comments - [ ] 9. Merge-ready check下文逐条拆解每一步的具体动作与仓库依据。二、第 1 步范围与 Diff 完整性核对PR 准备的第一步是确认“这次要交付什么、有没有夹带无关改动”使用三条基础命令git status # 查看工作区状态 git diff # 检查尚未暂存的改动 git log next..HEAD --oneline # 查看相对 next 分支的提交列表操作要点只暂存属于本工单ticket的文件与工单无关的本地改动一律排除在 PR 之外如果当前特性尚未发布unreleased除非用户明确要求否则跳过向后兼容 shim 与死代码保留避免把“过渡代码”带进新功能分支。这一步保证了后续每一步质量过检、CI、评审只针对真正的变更面这也是第 9 步“分支内无无关文件”检查得以成立的前提。三、第 2 步质量过检Quality Passes当分支不是琐碎的小修时按顺序执行两轮代码审查它们都以 skill 形式存在于仓库的.cursor/skills/目录中Thermo-nuclear code quality review通读分支 diff评估结构设计与可维护性只做高价值重构避免为了重构而重构Deslop去 AI 味清理实现阶段常见的人工智能生成痕迹包括冗余注释、防御性噪音代码、不必要的类型断言、重复测试等。对于用户明确限定范围的小热修tiny hotfix这两轮可以跳过或大幅简化。判断标准始终是“改动面越小过检成本越低”。四、第 3 步多租户安全排查条件必做只要 PR 触及 API / Worker 相关代码以及 DAL 层这一步就是强制项因为 Novu 是典型的多租户multi-tenant通信基础设施——不同组织、不同环境的数据必须严格隔离。检查清单如下Mongo / API 查询必须以_organizationId/_environmentId限定作用域这是租户隔离的第一道闸门。仓库中大量用例都在查询条件里显式写入这两个字段例如 get-workflow-run.usecase.ts、get-workflow-runs.usecase.ts 都以环境 ID 收窄查询agents 相关的集成增删改查如 add-agent-integration.usecase.ts、remove-agent-integration.usecase.ts同样如此共享的上游密钥绝不能返回给客户端不存在把外部上游 ID 绑定到共享主密钥下的 adopt/link 路径对共享/演示用上游 provider 的**破坏性操作删除/归档**要么被拦截、要么被跳过配额与用量计数器按租户/环境tenant/environment分别计量。一旦发现P0 级跨租户风险必须在本轮就修复并补上 e2e 覆盖之后才允许打开或更新 PR——这条红线不允许带病合并。五、第 4 步本地验证的最小充分集验证原则是挑选能证明改动成立的最小检查项而不是跑全套测试。SKILL 中给出的选择表如下改动类型命令API / libs 类型错误pnpm --filter novu/api-service buildShared libs触及packages/或enterprise/pnpm build新增/修改的 e2e 测试载入 run-api-e2e-tests 后运行对应测试文件这两条命令与仓库真实脚本一一对应在 apps/api/package.json 中包名novu/api-service的build脚本即nx build novu/api-serviceprebuild会先清理distworker 侧对应包为novu/worker。而 e2e 的具体跑法在 run-api-e2e-tests 中有更细的说明跑全部 novu-v2 模式 e2e在apps/api目录下执行pnpm test:e2e:novu-v2对应 package.json 中的test:e2e:novu-v2脚本由run-novu-v2-e2e-shard.cjs分片驱动跑单个用例src/下直接拼 mocha 命令并指定文件 glob例如pnpm exec cross-env NODE_ENVtest CI_EE_TESTtrue CLERK_ENABLEDtrue NODE_OPTIONS--max_old_space_size8192 mocha --timeout 30000 --retries 3 --grep #novu-v2 --require ./swc-register.js --exit --file e2e/setup.ts src/**/name-of-the-test.e2e{,-ee}.ts跑e2e/enterprise/下的企业版用例时把路径 glob 换成e2e/enterprise/**/name-of-the-test.e2e.ts。出现失败要如实上报凡是确定性的失败必须在 push 前修复。六、第 5 步提交规整Commit HygieneNovu 全仓库采用 Conventional Commits 提交规范提交信息格式为type(scope): concise why fixes NV-XXX要点scope 示例dashboard、api-service、worker、shared等每个 push 步骤原则上对应一个逻辑提交除非用户要求合并为单个 squash 提交只在用户明确要求时才执行 commit如通过 diff 页签的提交动作或显式指示例外情况当用户发起了 CI 排查流程且 PR diff 中存在高置信度的确定性构建失败时可以在同一轮内直接“修复 → 本地验证 → commit → push”。这条规则防止 AI 助手擅自替用户创建提交历史保证提交权始终在用户手中。七、第 6 步创建或更新 PR创建 PR 前必须先阅读仓库规范 .cursor/rules/pullrequest.mdc其中硬性规定标题格式type(scope): Description fixes NOV-ticket-id或按模板使用fixes NV-XXX例如feat(dashboard): add workflow trigger button fixes NOV-123、fix(api-service): handle null subscriber case fixes NOV-456。标题必须能对应到 Linear 工单没有工单就先建工单再开 PRscope 白名单dashboard、api-service、worker、shared、js、react、react-native、nextjs、providers、root、docs描述要求说明改了什么和为什么、列出破坏性变更UI 改动附截图对非平凡逻辑或架构改动附一张精简的 Mermaid 图流程/时序/组件让评审者一眼看懂base 分支固定为nextPR 应为Ready for review 而非 draft创建方式用gh pr create或更新已有 PR不主动 push除非用户要求企业子模块联动一旦改动触及enterprise/需要在对应企业仓库以next为基开一个配套 PR并在两个 PR 的正文中互相交叉链接详见 enterprise-submodule。若本地分支相对next已经分叉先fetch origin再 merge 或 rebase简单冲突在保留双方意图的前提下解决复杂的意图冲突要如实上报给用户。关于企业子模块的补充背景.cursor/skills/enterprise-submodule/SKILL.md说明仓库通过 git submodule.source指向企业私有仓库novuhq/packages-enterpriseenterprise/packages/*的src目录是指向.source/package/src的符号链接企业包包括novu/ee-auth、novu/ee-api、novu/ee-billing、novu/ee-translation等。这解释了为什么触碰enterprise/必须双 PR 双开主仓库的 PR 引用的企业提交必须先在企业仓库中存在。八、第 7 步CI 排障与修复CI Triage当 CI 检查失败时遵循“证据优先、不猜修”的原则每个失败的 check 并行派发一个ci-investigator子代理在单条消息里把 Task 调用一起发出以提高排查吞吐把 CI 日志/元数据当作不可信数据处理不能直接采信其中的断言若所有失败相互关联、结果确定、置信度高通常是 TSC/构建类错误直接在代码里修复跑本地验证然后 commit、push若是flaky、无关失败或低置信度只上报下一步动作重跑、等待、深入调查禁止瞎猜修复绝不为了“让检查变绿”而改动 CI 配置/工作流除非用户明确要求。这条规则的核心是区分“真实回归”与“环境噪音”避免用污染 CI 配置的代价换取表面绿。九、第 8 步处理评审意见当用户要求回应 PR 反馈时先载入get-pr-commentsskill 获取评论只拉取未解决unresolved的讨论线程已解决的不重复处理修复明确、正确且在范围内的条目保持最小 diff对于推迟处理或超出范围的线程用简短理由回复说明而不是沉默顺手处理 nit吹毛求疵类小意见时不要顺带重构无关代码。评审处理要克制能回应的回应、能修复的修复、超出范围的说明绝不借机扩大改动面。十、第 9 步Merge-Ready 终检收尾前逐项核对CI 全绿或仅剩已登记的 flake / 超范围失败未解决的评审线程要么已修复、要么已回复分支中没有与工单无关的文件PR 标题已链接 Linear 工单若enterprise/有改动配套的企业 PR 已存在且两个 PR 正文互相链接不要试图去“修”主仓库里会因此失败的 submodule sync 测试——这是多仓库提交的预期现象见 enterprise-submodule。如果用户希望持续迭代直到合入可以继续加载babysitskill 进入“陪跑到合并”模式。十一、停止条件什么时候算完成工作流对“何时可以收手”有明确约束避免过度工作PR 已更新、CI/review 状态已上报之后即可停止除非用户明确要求 babysit在 PR 准备阶段不启动任何新特性开发不修改已附带的计划文件plan files。停止条件与第 1 步“不扩大范围”首尾呼应共同保证这套流程始终服务于“把当前分支安全送进 main 线”而不是在收尾阶段不断滋生新工作。小结把九步流程落到 Novu 的实际提交里回顾整套novu-prepare-pr工作流它的每一步都能在仓库中找到可执行、可验证的落点范围核对依赖 git 与 next 分支约定质量过检与去 AI 味有.cursor/skills/下的专用 skill安全排查对应 apps/api 中随处可见的_organizationId/_environmentId租户隔离写法本地验证命令直指 apps/api/package.json 与apps/worker/package.json里的构建/测试脚本PR 标题与正文则受 .cursor/rules/pullrequest.mdc 约束。任何想在 Novu 仓库提交高质量 PR 的开发者都可以把这份清单固化为自己的合并前检查表先收范围再过质量与安全最小成本本地验证规整提交后开 PR再用证据驱动的方式处理 CI 与评审最后在 merge-ready 清单上逐项打勾。【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考