贡献给 n8n

相关源文件

• .devcontainer/Dockerfile
• .github/ISSUE_TEMPLATE/01-bug.yml
• .github/actions/setup-and-build/action.yml
• .github/workflows/check-documentation-urls.yml
• .github/workflows/check-pr-title.yml
• .github/workflows/check-run-eligibility.yml
• .github/workflows/chromatic.yml
• .github/workflows/ci-master.yml
• .github/workflows/ci-postgres-mysql.yml
• .github/workflows/ci-pull-requests.yml
• .github/workflows/docker-base-image.yml
• .github/workflows/docker-images-nightly.yml
• .github/workflows/e2e-flaky.yml
• .github/workflows/e2e-reusable.yml
• .github/workflows/e2e-tests-pr.yml
• .github/workflows/e2e-tests.yml
• .github/workflows/linting-reusable.yml
• .github/workflows/release-create-pr.yml
• .github/workflows/release-publish.yml
• .github/workflows/release-push-to-channel.yml
• .github/workflows/security-trivy-scan-callable.yml
• .github/workflows/test-workflows-nightly.yml
• .github/workflows/test-workflows-pr-approved.yml
• .github/workflows/test-workflows-pr-comment.yml
• .github/workflows/units-tests-reusable.yml
• CONTRIBUTING.md
• codecov.yml
• packages/@n8n/integration-test-utils/.eslintrc.js
• packages/@n8n/integration-test-utils/package.json
• packages/@n8n/integration-test-utils/src/index.ts
• packages/@n8n/integration-test-utils/tsconfig.build.json
• packages/@n8n/integration-test-utils/tsconfig.json
• packages/cli/bin/n8n
• turbo.json

本指南提供了有关如何为 n8n 代码库做出贡献的全面信息。它涵盖了开发设置、贡献工作流程、测试程序和 CI/CD 管道。有关创建自定义节点的信息，请参阅 节点系统文档。

开发环境设置

存储库结构

n8n 被组织成一个多包的 monorepo，通过 pnpm workspaces 进行管理。

来源：CONTRIBUTING.md44-62

要求

在设置 n8n 进行开发之前，请确保您具备以下先决条件

• Node.js：版本 22.16 或更高版本
• pnpm：版本 10.2 或更高版本（建议通过 corepack 安装）
• 构建工具：某些依赖项需要

构建工具安装

# Debian/Ubuntu
apt-get install -y build-essential python

# CentOS
yum install gcc gcc-c++ make

# Windows
npm add -g windows-build-tools

# MacOS
# No additional packages required

来源：CONTRIBUTING.md75-123

设置过程

1. Fork n8n 存储库
2. Clone 你的 fork 后的存储库

3. 导航到存储库文件夹

4. 将原始 n8n 存储库添加为上游

5. 安装依赖项并链接模块

6. 构建所有包

来源：CONTRIBUTING.md125-161

启动 n8n 进行开发

要以开发模式启动 n8n

这将自动构建你的代码，重启后端，并在你进行每次更改时刷新前端。

用于生产模式测试

启动带隧道（用于 webhook 测试）的 n8n

来源：CONTRIBUTING.md163-176 packages/cli/bin/n8n1-68

开发工作流

典型的开发工作流程包括以下步骤

来源：CONTRIBUTING.md177-198

社区 PR 指南

提交 PR 到 n8n 时，请遵守以下指南

响应时间要求

• 在 14 天内处理请求的更改或提供反馈
• 14 天内无活动的 PR 将被自动关闭

通用要求

1. 遵循样式指南:

   • 遵守 n8n 的编码标准和约定
   • 在适用的地方使用 linting 工具

2. TypeScript 合规性:

   • 不要使用 ts-ignore
   • 确保代码符合 TypeScript 规则

3. 避免重复代码:

   • 重用现有组件、参数和逻辑
   • 对于节点：如果适用，请在多个操作中使用相同的参数

4. 测试要求:

   • PR **必须包含测试**
     • 单元测试
     • 节点的流程测试
     • UI 测试（如适用）

5. 拼写错误:

   • 使用拼写检查工具避免拼写错误

PR 特定要求

1. 仅提交小型 PR:

   • 每个 PR 专注于一个功能或修复

2. 命名约定:

   • 遵循 n8n 的 PR 标题约定

3. 新节点:

   • 除非 n8n 团队明确要求，否则引入新节点的 PR 将被自动关闭

4. 仅拼写错误的 PR:

   • 拼写错误不足以证明 PR 的合理性

来源：CONTRIBUTING.md202-241

测试套件

n8n 拥有一个全面的测试套件，包括单元测试、代码覆盖率跟踪和端到端测试。

单元测试

单元测试可以通过以下方式运行

在特定的包文件夹中执行时，它将只运行该包的测试。在 n8n 根文件夹中执行时，它将运行所有包中的所有测试。

如果您进行的更改需要更新 .test.ts.snap 文件，请将 -u 传递给命令，或在监视模式下按 u。

来源：CONTRIBUTING.md247-259

代码覆盖率

n8n 在 Codecov 上跟踪所有代码的代码覆盖率。当您在本地处理测试时，可以通过设置 COVERAGE_ENABLED 环境变量为 true 来运行测试。

您可以在 coverage 文件夹中查看代码覆盖率，或者使用像 Coverage Gutters 这样的 VSCode 扩展直接在编辑器中可视化覆盖率。

来源：CONTRIBUTING.md261-264 codecov.yml1-69

端到端测试

在第一次运行 E2E 测试之前，您需要安装 Cypress

E2E 测试可以通过以下任一命令启动

• pnpm test:e2e:ui：以交互方式启动 n8n 并运行 e2e 测试，使用内置的 UI 代码
• pnpm test:e2e:dev：以开发模式启动 n8n 并以交互方式运行 e2e 测试
• pnpm test:e2e:all：启动 n8n 并无头运行 e2e 测试

来源：CONTRIBUTING.md266-276

CI/CD 流水线

n8n 使用 GitHub Actions 进行持续集成和部署。CI/CD 管道包括用于测试、构建和发布 n8n 的各种工作流。

来源：.github/workflows/ci-master.yml1-81 .github/workflows/ci-pull-requests.yml1-50 .github/workflows/release-create-pr.yml1-72 .github/workflows/release-publish.yml1-220 .github/workflows/docker-images-nightly.yml1-59

拉取请求工作流程

当你提交一个 PR 时

1. GitHub Actions 将会运行

   • 代码检查（Linting）
   • 单元测试
   • PR 标题验证
   • 类型检查

2. 如果 PR 被维护者批准，将触发其他工作流

   • 端到端测试
   • 设计系统测试（如适用）

3. 所有测试必须通过才能合并 PR

来源：.github/workflows/ci-pull-requests.yml1-50 .github/workflows/check-pr-title.yml1-37 .github/workflows/e2e-tests-pr.yml1-80

发布流程

n8n 使用结构化的发布流程

1. 发布流程由触发 release-create-pr.yml 工作流来启动。

2. 此工作流：

   • 更新已更改包的版本
   • 更新变更日志
   • 创建一个名为 release/${VERSION} 的新分支
   • 创建一个拉取请求以跟踪发布的更改

3. 一旦发布拉取请求被合并，release-publish.yml 工作流将执行以下操作：

   • 构建并发布到 NPM
   • 创建 Docker 镜像
   • 创建 GitHub 发布
   • 创建 Sentry release 以进行错误跟踪

来源: CONTRIBUTING.md278-292 .github/workflows/release-create-pr.yml1-72 .github/workflows/release-publish.yml1-220

数据库测试

n8n 支持多种数据库系统，并为每种支持的数据库包含自动化测试

• SQLite（默认）
• PostgreSQL
• MySQL
• MariaDB

CI 流水线包含针对这些数据库的测试工作流，以确保兼容性。

来源: .github/workflows/ci-postgres-mysql.yml1-230

贡献者许可协议

在您的贡献被合并之前，您需要签署一份贡献者许可协议 (CLA)。这是一个简单的过程

1. 当您打开一个拉取请求时，一个自动机器人会留下评论请求签署协议
2. CLA 来自 Indie Open Source，只有几行内容
3. 在获得签名之前，无法合并拉取请求

来源: CONTRIBUTING.md309-316

其他贡献机会

创建自定义节点

您可以通过 npm 创建社区节点并使其可用。有关构建节点的更多信息，请参阅 节点系统文档。

来源: CONTRIBUTING.md294-296

扩展文档

n8n 文档 docs.n8n.io 的代码库可以在 here 找到。

来源: CONTRIBUTING.md298-300

贡献工作流模板

您可以将您的工作流提交到 n8n 的模板库。n8n 正在开发一个创作者计划，并开发一个模板市场。有关如何提交模板和成为创作者的信息，请参阅 n8n Creator hub。

来源: CONTRIBUTING.md302-307

行为准则

本项目以及所有参与者都受《行为准则》的约束，该准则可在 CODE_OF_CONDUCT.md 文件中。通过参与，您需要遵守此代码。请将不可接受的行为报告给 jan@n8n.io。

来源: CONTRIBUTING.md37-42