跳转到内容
Remix Logo Remix Logo Remix 中文文档

Contributing

为 Remix 做贡献

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

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

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

贡献者许可协议

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

当你发起拉取请求时，remix-cla-bot 会提示你审查 CLA 并通过在 contributors.yml 中添加你的名字来签名

阅读 CLA

角色

本文档参考具有以下角色的贡献者：

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

开发过程

功能开发

如果您对新功能有想法，请不要发送 Pull 请求，而是遵循此流程：

  1. 贡献者将提案添加到[GitHub 讨论][提案]。
  2. Remix 管理团队在路线图规划会议中接受提案。
  • 当管理员根据提案创建问题并将问题添加到[路线图][路线图]时，提案即被接受。
  1. 管理员为问题指定所有者。
  • 所有者负责发布功能，包括 API、行为和实施的所有决策。
  • 所有者与其他贡献者一起组织工作以解决更大的问题。
  • 所有者可能是 Remix 团队内部或外部的贡献者。
  1. 所有者根据提案创建RFC，然后即可开始开发。
  2. 强烈建议结对，尤其是在开始时。

错误修复请求

如果您认为您发现了错误，我们很乐意通过 PR 来修复它！请遵循以下准则：

  1. 贡献者在 Pull 请求中添加失败测试和修复
  • 理想情况下，第一次提交是失败测试，然后对代码进行更改以修复它。
  • 这不是严格执行的，但非常值得赞赏！
  1. 管理员将作为路线图规划的一部分审查开放的错误修复 PR。
  • 简单的错误修复将当场合并。
  • 其他人将被添加到路线图中，并被分配一个所有者来审查工作并完成它。

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

错误报告问题

如果您认为发现了错误，但没有时间发送 PR，请遵循以下准则：

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

  1. 如果这不可能（与某些托管设置等相关），请创建一个 GitHub repo，我们可以根据 README 中的明确说明运行它来观察错误。

  2. 打开一个问题并链接到重现问题。

没有重现的错误报告将被立即关闭，并要求重现。

路线图规划会议

您可以随时在我们的直播规划会议中了解 Remix 的开发情况：

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

问题追踪

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

  • 原始问题将保留在路线图项目中，以查看总体进展。
  • 子任务将在临时项目上进行跟踪。
  • 工作完成后，临时项目将被归档。
  • 所有者负责向子项目中填充问题，并将工作拆分为可交付的工作块。
  • 鼓励在长期运行的分支上使用构建/功能标记。

RFC

  • 所有计划中的问题都必须在官方 RFC 讨论类别中发布 RFC，之后问题才能从_计划_状态变为_进行中_状态。
  • 某些提案可能已经是足够的 RFC，只需移至官方 RFC 讨论类别即可。
  • 发布 RFC 后，即可开始开发，但所有者应考虑社区的反馈，在必要时改变方向。

对业主的支持

  • 所有者将被添加到 Discord 上的 #collaborators 私人频道，以获得架构和实施方面的帮助。此频道是私人频道，有助于将噪音降至最低，以便管理员不会错过消息，所有者可以解除屏蔽。所有者还可以在任何频道或任何地方讨论这些问题！
  • 管理员将积极与所有者合作，确保他们的问题和项目井然有序（正确状态、相关问题的链接等）、记录在案并向前推进。
  • 如果进展停滞不前，问题的所有者可能会被重新分配。

每周路线图回顾

每周一次，Remix 团队和任何外部所有者都会被邀请审查路线图

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

合作者的角色

为了帮助保持存储库整洁有序，合作者将采取以下措施：

问题标签

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

拉取请求选项卡

  • 未经过开发流程的功能将立即关闭，并要求开启讨论。
  • 没有测试用例的错误修复 PR 可能会立即关闭，要求进行测试。（有些东西很难测试，合作者会酌情决定。）

开发设置

在为代码库做出贡献之前，您需要 fork 仓库。根据您做出的贡献类型，这会有所不同：

以下步骤将帮助您为该 repo 做出贡献：

  1. Fork 该 repo（点击本页面右上角的 Fork 按钮）。

  2. 在本地克隆你的 fork。

Terminal window
# 在终端中，cd 到你想要克隆的父目录，然后
git clone https://github.com/<your_github_username>/remix.git
cd remix


# 如果您要进行*任何*代码更改，请确保签出 dev 分支
git checkout dev

  1. 运行 pnpm 安装依赖项。如果使用 npm 安装，将生成不必要的 package-lock.json 文件。

  2. 通过运行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 测试：主要 - pnpm 测试：集成

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

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

我们也有针对这些的监视模式插件。因此，您可以运行pnpm test:primary --watch并点击w来查看可用的监视命令。

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

开发工作流程

软件包

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

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

建筑

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

游乐场

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

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

Terminal window
pnpm playground:new <?name>

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

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

测试

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

Terminal window
# Test all packages
pnpm test


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

存储库分支

此 repo 维护了用于不同目的的单独分支。它们看起来如下所示：

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

可能还有其他分支用于各种功能和实验，但所有神奇的事情都发生在这些分支上。

夜间发布如何进行？

夜间版本将运行来自main分支的操作文件，因为预定的工作流程将始终使用对默认分支的最新提交，由 夜间操作文件上的此评论 表示，但是它们在设置期间签出dev分支，因为我们希望从那里剪切夜间版本。从那里，我们检查 git SHA 是否相同，并且只有在发生更改时才剪切新的夜间版本。

端到端测试

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