n8n:create-pr

创建 Pull Request

创建标题符合 n8n check-pr-title CI 验证要求的 GitHub PR。

PR 标题格式

<type>(<scope>): <summary>

类型（必填）

类型	说明	变更日志
feat	新功能	是
fix	修复缺陷	是
perf	性能改进	是
test	添加或修正测试	否
docs	仅涉及文档	否
refactor	代码变更（不修复缺陷，也不添加功能）	否
build	构建系统或依赖项	否
ci	CI 配置	否
chore	常规任务、维护	否

范围（可选，但建议填写）

• API - 公共 API 变更
• ai-builder - AI 工作流构建器和 Instance AI
• benchmark - Benchmark CLI 变更
• core - 核心／后端／私有 API
• editor - 编辑器 UI 变更
• engine - 新的工作流执行引擎 v2（@n8n/engine 包和 cli 中的 engine-v2 模块）
• * Node - 特定节点（例如：Slack Node、GitHub Node）

check-pr-title 仅接受这些范围。请勿将包名或文件夹名用作范围（例如 instance-ai、cli、evals 或 docker）。 如果没有合适的范围，请省略范围。若要填写两个范围，请用逗号和空格分隔：fix(core, editor): ...。

摘要规则

• 使用祈使语气的现在时：“Add”，而不是“Added”
• 首字母大写
• 末尾不加句号
• 不要包含工单 ID（例如 N8N-1234）
• 添加 (no-changelog) 后缀以排除在变更日志之外，除非该类型本身已排除

步骤

1. 检查当前状态：

   git status
   git diff --stat
   git log origin/master..HEAD --oneline
   

2. 检查是否有实现计划：在仓库的计划目录（若存在，则为 .claude/plans/ 或 .agents/plans/）中查找与当前分支工单 ID 匹配的计划文件（例如，如果分支名为 scdekov/PAY-1234-some-feature，则查找 PAY-1234.md）。 如果存在计划文件，询问用户是否要将其作为可折叠的 <details> 部分加入 PR 描述（见下文的“计划部分”）。 只有在用户明确同意后，才能加入计划。

3. 如果这是安全修复，请在继续之前审核所有面向公众的内容（见下文的“安全修复”）。

4. 分析变更，确定：

   • 类型：这是什么类型的变更？
   • 范围：Scopes 列表中的哪个范围适用？如果都不适用，则省略范围。
   • 摘要：变更做了什么？以大写字母开头。

5. 必要时推送分支：

   git push -u origin HEAD
   

6. 使用 gh CLI 创建 PR。读取 .github/pull_request_template.md，并将其作为正文结构，然后在创建 PR 前为每个部分填写实际内容：

   • Summary：描述 PR 的内容
   • Why：说明为什么需要此变更（见下文的“原因”）
   • How to test：说明如何测试这些变更。适当时提供工作流示例
   • Related tickets：添加 Linear 工单 URL（https://linear.app/n8n/issue/[TICKET-ID]）和任何 GitHub issue 链接
   • Checklist：保持模板原样
     • 在正文末尾添加“🤖 PR Summary generated by AI”

   创建 PR 前，请按以下要求校对正文。重写所有不符合要求的句子：

   1. Summary 和 Why 的字数合计未超过字数限制。如果超出，先删去评审者可在差异中看到的细节，再缩短 Why。
   2. 每个句子都明确说明谁做了什么：以组件、流程或人员为主语，并使用直白的技术动词。
   3. 每个领域术语首次出现时，都有直白的定义。
   4. 每个句子都与差异内容相符。

   后续提交如果改变了正文中的事实，请更新正文。

   gh pr create --draft --title "<type>(<scope>): <summary>" --body "$(cat <<'EOF'
   <populated body based on pull_request_template.md>
   EOF
   )"
   

PR 正文指南

依据 .github/pull_request_template.md：

面向不了解这部分代码的评审者撰写。评审者在查看差异前必须理解变更。使用 ASD-STE100 简明技术英语：句子简短，使用主动语态。

1. Summary 和 Why 合计控制在约 200 个单词以内。小型 PR 的字数应少得多。
2. 每个领域术语首次出现时，都用直白的语言解释。不要用工单 ID 或内部名称作解释。
3. 省略评审者可在差异中看到的细节：错误情况、状态码、重命名的字段、调用顺序、文件列表、测试名称。只有在这些细节会改变评审者可能忽略的行为时，才提及其中一项。也省略评审者已了解的内容（框架行为）。
4. 使用直白的技术动词，不要使用比喻（“传递值”，而不是“交出值”或“让值通过”）。

Summary：PR 的内容

1. 先用一到三句话介绍背景，让新读者了解相关领域。然后说明 PR 做了什么。
2. 使用文字叙述描述行为，而不是罗列代码改动。当类或函数代表核心概念且有助于读者了解变更时，请注明其名称。
3. 如果 PR 未更改产品代码，请在第一句话中说明（例如：“此 PR 仅添加测试。”）。
4. 不要在此处说明变更的理由。理由应写在 Why 中。
5. 对于 UI 变更，请附上截图或视频。

Why：原因

始终填写 ## Why 部分。摘要和 Why 的核心内容是审阅者最需要了解的。核心内容要简短：

1. 不要重复摘要。
2. 说明导致现有代码不适用的问题或限制。
3. 如果存在已接受的差距，或更改了现有代码路径，请另起一段简短说明。

只有在不说明替代方案会让审阅者产生疑问时，才补充被否决的方案（如有）。每个替代方案用一两句话说明具体原因，指出它为何行不通。对于从未实现的方案，请用条件句表述。所有替代方案加起来必须短于 Why 部分的核心内容。

如何测试部分

• 说明如何测试这些更改
• 适当时，提供示例工作流
• 如果该功能在默认的 n8n 实例中不可用（需要通过 N8N_ENABLED_MODULES 启用非默认模块、企业许可证、功能标志或类似配置），请注明测试者部署正确配置的实例所需的环境变量或许可证

相关链接部分

• 添加 Linear 工单链接：https://linear.app/n8n/issue/[TICKET-ID]
• 添加 GitHub 问题链接，并使用关键字自动关闭：
  • closes #123 / fixes #123 / resolves #123
• 如适用，添加 Community 论坛帖子链接

检查清单

合并前应完成以下所有事项：

• PR 作者本人已勾选“I have seen this code, I have run this code, and I take responsibility for this code.”复选框
• PR 标题符合约定
• 已更新文档，或已创建后续工单
• 已包含测试（Bug 需要回归测试，功能需要测试覆盖）
• 如果紧急修复需要回移植，已添加 release/backport 标签

示例

编辑器功能

feat(editor): Add workflow performance metrics display

核心 Bug 修复

fix(core): Resolve memory leak in execution engine

特定节点的更改

fix(Slack Node): Handle rate limiting in message send

破坏性更改（在冒号前添加感叹号）

feat(API)!: Remove deprecated v1 endpoints

无变更日志条目

feat(core): Experimental feature not enabled yet (no-changelog)

无作用范围（影响多个区域）

chore: Update dependencies to latest versions

验证

PR 标题必须符合以下格式：

^(feat|fix|perf|test|docs|refactor|build|ci|chore|revert)(\((API|core|editor|benchmark|ai-builder|engine|[A-Za-z0-9 .]+ Node)(, (API|core|editor|benchmark|ai-builder|engine|[A-Za-z0-9 .]+ Node))*\))?!?: [A-Z].+[^.]$

关键验证规则：

• 类型必须是允许的类型之一
• 作用范围可选，但如果填写，必须放在括号中，且属于 Scopes 列表（或 <display name> Node）
• 破坏性更改的感叹号必须放在冒号前
• 摘要必须以大写字母开头
• 摘要不能以过去时动词（Added）开头
• 摘要不能以句号结尾
• 不能包含工单号（N8N-1234）或 PR 号（#12345）
• 如果使用 (no-changelog)，必须将其放在摘要末尾

运行 gh pr create 前，请根据这些规则检查标题。最常见的两类错误是将软件包名称用作作用范围，以及摘要首字母小写。

计划部分

如果在仓库的计划目录中找到了匹配的计划文件，且用户已批准将其纳入，请在 PR 正文末尾（检查清单之后、EOF 之前）添加一个可折叠部分：

<details>
<summary>Implementation plan</summary>



</details>

安全修复

此仓库是公开的。 切勿在任何公开内容中泄露攻击途径。描述代码的作用，而不是它防范的威胁。

内容	不推荐	推荐
分支	fix-sql-injection-in-webhook	fix-webhook-input-validation
PR 标题	fix(core): Prevent SSRF	fix(core): Validate outgoing URLs
提交信息	fix: prevent denial of service	fix: add payload size validation
PR 正文	“攻击者可触发 SSRF……”	“验证 URL 协议和主机”
Linear 引用	带 slug 的 URL（会泄露标题）	不带 slug 的 URL，或仅包含工单 ID
测试名称	'should prevent SQL injection'	'should sanitize query parameters'

推送安全修复前，请确认： 分支名称、提交、PR 标题、PR 正文、Linear URL、测试名称或代码注释中均没有暗示漏洞的信息。

如有疑问，请查看 Linear 工单，了解可能需要采取的额外预防措施。