为 Remix 做出贡献

我们的目标是让 Remix 的开发稳定、可靠和开放。没有我们出色的用户社区，我们就无法做到这一点！

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

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

贡献者许可协议

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

当您开始拉取请求时，remix-cla-bot 将提示您查看 CLA 并通过将您的姓名添加到 contributors.yml 来签署它

阅读 CLA

角色

本文档中提到的贡献者具有以下角色

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

开发流程

功能开发

如果您有新功能的想法，请不要发送拉取请求，而是遵循此过程

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

Bug 修复 Pull Request

如果您认为自己找到了 bug，我们很乐意收到修复它的 PR！请遵循以下准则

1. 贡献者在 Pull Request 中添加失败的测试以及修复。
   • 理想情况下，第一个 commit 应该是失败的测试，然后是对代码进行修复的更改。
   • 这不是强制执行的，但非常感谢！
2. 管理员将在路线图规划中审查未完成的 bug 修复 PR。
   • 简单的 bug 修复将当场合并。
   • 其他修复将被添加到路线图中，并分配一个负责人来审查工作并使其完成。

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

Bug 报告 Issue

如果您认为自己找到了 bug 但没有时间发送 PR，请遵循以下准则

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

   • https://remix.new 使这个过程非常容易

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

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

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

路线图规划会议

您始终可以在我们的直播规划会议中查看 Remix 的开发情况

• Remix 管理团队将每周举行会议，向社区报告进展情况，并将提案和已验证的 Bug 添加到路线图中。
  • 要将提案添加到路线图，需要 Remix 管理团队达成一致意见。
  • 提案不会被“拒绝”，只会“接受”到路线图中。
  • 贡献者可以继续投票和评论提案，如果它获得新的活动，它将在未来的审查中浮出水面。
  • Remix 管理团队可能会出于任何原因锁定提案。
• 会议将在 Remix YouTube 频道上直播。
  • 在会议进行期间，欢迎大家加入 Discord #roadmap-livestream-chat 频道。
  • 欢迎 Remix 协作者参加。

Issue 跟踪

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

• 原始 issue 将保留在路线图项目中，以查看总体进展情况。
• 子任务将在临时项目中跟踪。
• 当工作完成时，临时项目将被存档。
• 负责人负责使用 issue 填充子项目，并将工作分解为可交付的工作块。
• 鼓励使用构建/功能标志，而不是长期运行的分支。

RFC

• 所有计划的 Issue 都必须在 Issue 从“计划中”移动到“进行中”之前，在官方 RFC 讨论类别中发布 RFC。
• 有些提案可能已经是一个足够的 RFC，可以直接移动到官方 RFC 讨论类别。
• 发布 RFC 后，即可开始开发，但负责人应考虑社区的反馈，以便在需要时更改他们的方向。

对负责人的支持

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

每周路线图审查

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

• 识别阻塞因素
• 在团队和社区内寻找配对编程的机会

协作者的角色

为了帮助保持存储库的清洁和组织性，协作者将采取以下措施

Issues 选项卡

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

Pull Requests 选项卡

• 未经过 开发流程 的功能将立即关闭，并要求改为打开讨论。
• 没有测试用例的 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 使用单体仓库来托管多个包的代码。这些包位于 packages 目录中。

我们使用 pnpm 工作区来管理依赖项的安装和运行各种脚本。要安装所有内容，请从仓库根目录运行 pnpm install。

构建

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

Playground

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

要生成新的 playground，只需运行

pnpm playground:new <?name>

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

从 pnpm playground:new 生成的 playground 基于 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 断言，以确保开发和部署的应用都能正常运行。