为 Remix 贡献代码

我们的目标是让 Remix 的开发稳定、可靠且开放。没有我们奇妙的用户社区，我们做不到！

本文档将帮助您熟悉我们的开发流程以及如何设置您的环境。

为了确保您的工作有最大的被接受机会，请在贡献任何内容之前阅读本文档！

贡献者许可协议

所有发送 Pull Request 的贡献者都需要签署贡献者许可协议 (CLA)，该协议明确地将贡献的所有权分配给我们。

当您启动 Pull Request 时，remix-cla-bot 将提示您查看 CLA 并通过在 contributors.yml 中添加您的姓名来签署它。

阅读 CLA

角色

本文档提到了以下角色的贡献者

• 管理员：拥有管理权限的 GitHub 组织团队，他们设置和管理路线图。
• 合作者：拥有写入权限的 GitHub 组织团队。他们管理问题、PR、讨论等。
• 贡献者：您！

开发流程

功能开发

如果您有关于新功能的想法，请不要发送 Pull Request，而是按照以下流程进行

1. 贡献者向 GitHub Discussions 添加一个提案。
2. Remix 管理团队在路线图规划会议上接受提案。
   • 当管理员从提案中创建一个问题并将该问题添加到 路线图 中时，提案被接受。
3. 管理员将一个所有者分配给该问题。
   • 所有者负责交付功能，包括所有有关 API、行为和实施的决策。
   • 所有者与其他贡献者一起组织更大问题的工作。
   • 所有者可以是 Remix 团队内部或外部的贡献者。
4. 所有者从提案中创建一个RFC，然后可以开始开发。
5. 鼓励结对编程，特别是在开始阶段。

Bug 修复 Pull Requests

如果你认为你发现了错误，我们非常希望你能提交一个 PR 来修复它！请遵循以下指南

1. 贡献者在拉取请求中添加一个失败的测试以及修复方案
   • 理想情况下，第一个提交是一个失败的测试，然后是修复该测试的代码更改。
   • 这并非强制要求，但非常受欢迎！
2. 管理员将在路线图规划中审核开放的 bug 修复 PR。
   • 简单的 bug 修复将立即合并。
   • 其他修复将被添加到路线图中，并分配给一个负责人来审核工作并将其完成。

没有测试用例的 bug 修复 PR 可能会立即被关闭（有些东西很难测试，我们会酌情处理）

Bug 报告问题

如果你认为你发现了错误，但没有时间提交 PR，请遵循以下指南

1. 在 Stackblitz、Replit、CodeSandbox 等地方创建一个问题的最小重现，我们可以访问并观察错误

   • https://remix.new 使这变得非常容易

2. 如果这不可行（与某些托管设置相关等），请创建一个 GitHub 仓库，我们可以运行该仓库，并在 README 中提供清晰的说明来观察错误。

3. 打开一个 issue 并链接到重现。

没有重现的 bug 报告将立即被关闭，并要求提供重现。

路线图规划会议

你始终可以在我们的直播规划会议中了解 Remix 的开发情况

• Remix 管理团队将每周开会，向社区汇报进度，并将提案和已验证的错误添加到路线图中。
  • 将提案添加到路线图中需要 Remix 管理团队的一致同意。
  • 提案不会被“拒绝”，只会被“接受”到路线图中。
  • 贡献者可以继续点赞和评论提案，如果提案有新的活动，它们将在未来的审核中浮出水面。
  • Remix 管理团队可能会出于任何原因锁定提案。
• 会议将在 Remix YouTube 频道 上直播。
  • 会议进行期间，每个人都可以在 Discord 的 #roadmap-livestream-chat 频道中参与讨论。
  • 邀请 Remix 协作者参加。

问题跟踪

如果路线图问题预计很大（涉及多个任务、作者、PR 等），管理员团队将创建一个临时项目看板。

• 原始问题将保留在路线图项目中，以便查看总体进度。
• 子任务将在临时项目中跟踪。
• 工作完成后，临时项目将被存档。
• 负责人负责在子项目中添加问题，并将工作分解成可交付的工作块。
• 鼓励使用构建/功能标记而不是长期分支。

RFC

• 所有计划中的问题都必须在问题从“已计划”状态变为“进行中”状态之前，在官方 RFC 讨论类别中发布一个 RFC。
• 一些提案可能已经足够充当 RFC，只需将其移动到官方 RFC 讨论类别中即可。
• 一旦 RFC 发布，开发就可以开始了，但预计负责人会考虑社区的反馈，并在需要时调整他们的方向。

对负责人的支持

• 负责人将被添加到 Discord 上的 #collaborators 私人频道，以获得有关架构和实现方面的帮助。该频道是私人的，以帮助尽量减少噪音，使管理员不会错过信息，并且负责人可以解除阻塞。负责人也可以在任何频道或任何地方讨论这些问题！
• 管理员将积极与负责人合作，确保他们的问题和项目井井有条（正确的状态、相关问题的链接等）、有文档记录，并不断向前推进。
• 如果进度停滞，问题的负责人可能会被重新分配。

每周路线图审查

每周一次，Remix 团队和任何外部负责人被邀请审查路线图

• 识别阻碍因素
• 在团队和社区内寻找结对机会

协作者的角色

为了帮助保持代码库的整洁和组织，协作者将采取以下行动

问题选项卡

• 没有重现的 bug 报告将立即被关闭，并要求提供重现。
• 应为提案的问题将被转换为提案。
• 问题将被转换为问答讨论。
• 具有有效重现的问题将被标记为已验证的错误，并由管理员在路线图规划会议中添加到路线图中。

拉取请求选项卡

• 没有经过开发流程的功能将立即被关闭，并要求打开一个讨论。
• 没有测试用例的 bug 修复 PR 可能会立即被关闭，并要求提供测试。（有些东西很难测试，协作者会酌情处理。）

开发设置

在你能够贡献代码之前，你需要 fork 代码库。这根据你所做贡献的类型略有不同

以下步骤将帮助你设置好，以便为该代码库贡献更改

1. fork 代码库（单击 此页面 右上角的 Fork 按钮）。

2. 将你的 fork 克隆到本地。

   # in a terminal, cd to parent directory where you want your clone to be, then
   git clone https://github.com/<your_github_username>/remix.git
   cd remix
   
   # if you are making *any* code changes, make sure to checkout the dev branch
   git checkout dev
   

3. 通过运行 pnpm 安装依赖项。如果你使用 npm 安装，则会生成不必要的 package-lock.json 文件。

4. 通过运行 npx playwright install 安装 Playwright 以便能够正确运行测试，或者 使用 Visual Studio Code 插件。

5. 通过运行 pnpm test 验证你是否已准备好进行本地开发。

分支

重要：在 GitHub 中创建 PR 时，确保将基线设置为正确的分支。

• dev 用于代码更改。
• main：用于文档更改和一些模板。

在 GitHub 中，你可以在“比较更改”标题下方的下拉菜单中设置基线，以创建 PR。

测试

我们在该项目中使用 jest 和 playwright 的混合来进行测试。我们在 integration 文件夹中有一套集成测试，每个包都有自己的 jest 配置，这些配置随后会被根目录中的主要 jest 配置引用。

集成测试和主要测试可以使用 npm-run-all 并行运行，以使测试尽可能快地高效地运行。要独立运行这两套测试，你需要运行单个脚本

• pnpm test:primary
• pnpm test:integration

我们还支持用于项目、文件和测试过滤的 watch 插件。要过滤内容，你可以使用 --testNamePattern、--testPathPattern 和 --selectProjects 的组合。例如

pnpm test:primary --selectProjects react --testPathPattern transition --testNamePattern "initial values"

我们还为这些插件提供了 watch 模式。因此，你可以运行 pnpm test:primary --watch 并按 w 查看可用的 watch 命令。

或者，你可以通过 cd 到该项目并运行 pnpm jest 来完全独立地运行项目，这将拾取该项目的 jest 配置。

开发工作流程

包

Remix 使用一个 monorepo 来托管多个包的代码。这些包位于 packages 目录中。

我们使用 pnpm workspaces 来管理依赖项的安装以及运行各种脚本。要安装所有内容，请从代码库根目录运行 pnpm install。

构建

从根目录运行 pnpm build 将运行构建。你可以在 watch 模式下使用 pnpm watch 运行构建。

游乐场

在开发应用程序的功能时，能够与真实应用程序进行交互通常非常有用。因此，你可以将应用程序放在 playground 目录中，构建过程会自动将所有输出复制到 playground 目录中所有应用程序的 node_modules 中。它甚至会为你触发一个实时重新加载事件！

要生成一个新的游乐场，只需运行

pnpm playground:new <?name>

其中游乐场的名称是可选的，默认为 playground-${Date.now()}。然后，你可以 cd 到为你生成的目录中，并运行 npm run dev。在另一个终端窗口中运行 pnpm watch，你就可以开始使用实时重新加载魔法 🧙‍♂️ 开发你喜欢的任何 Remix 功能了。

从 pnpm playground:new 生成的游乐场基于 scripts/playground/template 中的模板。如果你想更改模板中的任何内容，可以在 scripts/playground/template.local 中创建一个自定义模板，该模板被 .gitignored，因此你可以随意对其进行自定义。

测试

在运行测试之前，你需要运行构建。构建完成后，从根目录运行 pnpm test 将运行每个包的测试。如果你想运行特定包的测试，请使用 pnpm test:primary --selectProjects <display-name>

# Test all packages
pnpm test

# Test only @remix-run/express
pnpm test:primary --selectProjects express

代码库分支

该代码库维护着用于不同目的的独立分支。它们将看起来像这样

- main   > the most recent release and current docs
- dev    > code under active development between stable releases

可能存在其他分支用于各种功能和实验，但所有魔法都来自这些分支。

夜间版本是如何工作的？

夜间版本将运行 main 分支中的操作文件，因为计划的运行工作流始终使用默认分支的最新提交，如 夜间操作文件上的此注释 所示，但是它们在设置期间会检出 dev 分支，因为我们希望从那里发布夜间版本。然后，我们会检查 git SHA 是否相同，并且只有在发生更改时才会发布新的夜间版本。

端到端测试

对于每个 Remix 版本（稳定版、实验版、夜间版和预发布版），我们将在所有官方适配器上对 Remix 应用进行完整的端到端测试，从 `create-remix` 一直部署到生产环境。我们通过利用默认的 模板 和 Fly 和 Arc 的 CLI 来完成。然后，我们将运行一些简单的 Cypress 断言，以确保开发和部署的应用程序都能正常运行。