为 Remix 贡献

¥Contributing to Remix

我们的目标是让 Remix 开发稳健、稳定且开放。如果没有我们优秀的用户社区，我们无法做到这一点！

¥Our goal is for Remix development to be steady, stable, and open. We can't do that without our wonderful community of users!

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

¥This document will familiarize you with our development process as well as how to get your environment set up.

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

¥To ensure your work has the best chance of being accepted, please read this before contributing anything!

贡献者许可协议

¥Contributor License Agreement

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

¥All contributors sending a Pull Request need to sign the Contributor License Agreement (CLA) that explicitly assigns ownership of the contribution to us.

当你发起拉取请求时，remix-cla-bot 会提示你审核 CLA 并通过在 contributors.yml 上签名来签署。

¥When you start a pull request, the remix-cla-bot will prompt you to review the CLA and sign it by adding your name to contributors.yml

阅读 CLA

¥Read the CLA

角色

¥Roles

本文档面向具有以下角色的贡献者：

¥This document refers to contributors with the following roles:

• 管理员：拥有管理员权限的 GitHub 组织团队，他们负责设置和管理路线图。

  ¥Admins: GitHub organization team with admin rights, they set and manage the Roadmap.

• 协作者：GitHub 组织团队，拥有写入权限。它们管理问题、PR、讨论等。

  ¥Collaborators: GitHub organization team with write access. They manage issues, PRs, discussion, etc.

• 贡献者：你！

  ¥Contributors: you!

开发流程

¥Development Process

功能开发

¥Feature Development

如果你对新功能有想法，请不要发送拉取请求，而是按照以下流程操作：

¥If you have an idea for a new feature, please don't send a Pull Request, but follow this process instead:

1. 贡献者向 GitHub 讨论区 添加了提案。

   ¥Contributors add a Proposal to GitHub Discussions.

2. Remix 管理团队在路线图规划会议中接受提案。

   ¥The Remix Admin Team accepts Proposals in the Roadmap Planning meeting.

   • 当管理员根据提案创建问题并将其添加到 路线图 时，提案即被接受。

     ¥Proposals are accepted when the Admins create an Issue from the Proposal and add the issue to the Roadmap.

3. 管理员会为问题分配一个所有者。

   ¥The Admins assign an Owner to the issue.

   • 所有者负责交付该功能，包括所有关于 API、行为和实现的决策。

     ¥Owners are responsible for shipping the feature, including all decisions for APIs, behavior, and implementation.

   • 所有者会与其他贡献者一起组织工作以解决更大的问题。

     ¥Owners organize the work with other contributors for larger issues.

   • 所有者可以是 Remix 团队内部或外部的贡献者。

     ¥Owners may be contributors from inside or outside the Remix team.

4. 所有者根据提案创建 RFC，然后即可开始开发。

   ¥Owners create an RFC from the Proposal and development can begin.

5. 强烈建议结对开发，尤其是在初期。

   ¥Pairing is highly encouraged, particularly at the start.

错误修复拉取请求

¥Bug-Fix Pull Requests

如果你认为发现了错误，我们非常希望你提交一个可以修复该错误的 PR！请遵循以下准则：

¥If you think you've found a bug, we'd love a PR that fixes it! Please follow these guidelines:

1. 贡献者在拉取请求中添加失败测试并修复。

   ¥Contributors add a failing test along with the fix in a Pull Request

   • 理想情况下，第一次提交是失败的测试，然后对代码进行更改以修复它。

     ¥It's ideal if the first commit is a failing test followed by the changes to the code that fix it.

   • 这并非严格执行，但非常感谢！

     ¥This is not strictly enforced but very appreciated!

2. 管理员将审核未解决的错误修复 PR，作为路线图规划的一部分。

   ¥The Admins will review open bugfix PRs as part of Roadmap Planning.

   • 简单的错误修复将立即合并。

     ¥Simple bugfixes will be merged on the spot.

   • 其他人将被添加到路线图中，并被指派一名负责人来审查工作并完成最终工作。

     ¥Others will be added to the Roadmap and assigned an Owner to review the work and get it over the finish line.

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

¥Bug fix PRs without a test case might be closed immediately (some things are hard to test, we’ll use discretion here)

错误报告问题

¥Bug Report Issues

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

¥If you think you've found a bug but don't have the time to send a PR, please follow these guidelines:

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

   ¥Create a minimal reproduction of the issue somewhere like Stackblitz, Replit, CodeSandbox, etc. that we can visit and observe the bug:

   • [https://remix.new]https_remix_new 让这一切变得非常简单。

     ¥https://remix.new makes this really easy

2. 如果无法做到这一点（与某些托管设置等相关），请创建一个 GitHub 代码库，以便我们按照 README 中的明确说明运行该代码库来观察错误。

   ¥If this is not possible (related to some hosting setup, etc.), please create a GitHub repo that we can run with clear instructions in the README to observe the bug.

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

   ¥Open an issue and link to the reproduction.

没有复现代码的 Bug 报告将被立即关闭，并要求进行复现。

¥Bug reports without a reproduction will be immediately closed asking for a reproduction.

路线图规划会议

¥Roadmap Planning Meeting

你可以随时在我们的直播计划会议中查看 Remix 开发进度：

¥You can always check in on Remix development in our live-streamed planning meeting:

• Remix 管理团队将每周开会向社区汇报进度，并将提案和已验证的错误添加到路线图中。

  ¥The Remix Admin team will meet weekly to report progress to the community and add Proposals and Verified Bugs to the Roadmap.

  • 需要 Remix 管理员一致同意才能将提案添加到路线图。

    ¥Unanimous agreement among the Remix Admin is required to add a Proposal to the Roadmap.

  • 提案不会被“拒绝”，只会被“接受”并添加到路线图中。

    ¥Proposals are not “rejected”, only “accepted” onto the Roadmap.

  • 贡献者可以继续对提案点赞和评论。如果提案有新的活动，它们将会被添加到待审核的版本中。

    ¥Contributors can continue to upvote and comment on Proposals, they will bubble up for a future review if it’s getting new activity.

  • Remix 管理团队可能会因任何原因锁定提案。

    ¥The Remix Admin team may lock Proposals for any reason.

• 会议将在 Remix YouTube 通道 上进行直播。

  ¥The meeting will be livestreamed on the Remix YouTube channel.

  • 会议期间，诚邀各位参加 Discord #roadmap-livestream-chat。

    ¥Everyone is invited to the Discord #roadmap-livestream-chat while the meeting is in progress.

  • Remix 合作者诚邀参与。

    ¥Remix Collaborators are invited to attend.

问题跟踪

¥Issue Tracking

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

¥If a Roadmap Issue is expected to be large (involving multiple tasks, authors, PRs, etc.), a temporary project board will be created by the Admin team.

• 原始问题将保留在路线图项目中，以查看总体进展。

  ¥The original issue will remain on the Roadmap project to see general progress.

• 子任务将在临时项目上进行跟踪。

  ¥The subtasks will be tracked on the temporary project.

• 工作完成后，临时项目将被归档。

  ¥When the work is complete, the temporary project will be archived.

• 所有者负责向子项目提交问题，并将工作拆分成可交付的工作块。

  ¥The Owner is responsible for populating the subproject with issues and splitting the work up into shippable chunks of work.

• 鼓励在长期运行的分支上使用构建/功能标记。

  ¥Build / feature flags are encouraged over long-running branches.

RFCs

• 所有计划中的问题都必须在官方 RFC 讨论类别中发布 RFC，然后问题才能从“计划”变为“进行中”。

  ¥All Issues that are planned must have an RFC posted in the Official RFCs Discussion category before the Issue moves from Planned to In Progress.

• 一些提案可能已经是足够的 RFC，可以直接移至官方 RFC 讨论区。

  ¥Some Proposals may already be a sufficient RFC and can simply be moved to the Official RFCs Discussion category.

• RFC 发布后，开发即可开始，但开发者应考虑社区的反馈，并在必要时调整方向。

  ¥Once the RFC is posted, development can begin, though Owners are expected to consider the community's feedback to alter their direction when needed.

对所有者的支持

¥Support for Owners

• 所有者将被添加到 Discord 上的 #collaborators 私有通道，以获得架构和实现方面的帮助。此通道为私密通道，旨在最大程度地减少噪音，确保管理员不会遗漏任何消息，并且通道所有者可以解除屏蔽。所有者还可以在任何通道或任何地方讨论这些问题！

  ¥Owners will be added to the #collaborators private channel on Discord to get help with architecture and implementation. This channel is private to help keep noise to a minimum, so Admins don't miss messages and owners can get unblocked. Owners can also discuss these questions in any channel or anywhere!

• 管理员将积极与所有者合作，确保他们的问题和项目井然有序（状态正确、相关问题链接等）、记录完整并顺利推进。

  ¥Admins will actively work with owners to ensure their issues and projects are organized (correct status, links to related issues, etc.), documented, and moving forward.

• 如果进度停滞，问题的所有者可能会被重新分配。

  ¥An issue's Owner may be reassigned if progress is stagnating.

每周路线图回顾

¥Weekly Roadmap Reviews

Remix 团队和所有外部所有者每周都会受邀审查路线图一次。

¥Once a week, the Remix team and any external Owners are invited to review the Roadmap

• 识别阻碍因素

  ¥Identify blockers

• 在团队和社区内寻找结对机会

  ¥Find pairing opportunities within the team and the community

协作者角色

¥Collaborator's Role

为了帮助保持代码库的整洁有序，协作者将采取以下措施：

¥To help keep the repositories clean and organized, Collaborators will take the following actions:

问题选项卡

¥Issues Tab

• 没有复现代码的 Bug 报告将被立即关闭，并要求进行复现。

  ¥Bug reports without a reproduction will be immediately closed asking for a reproduction.

• 本应为提案的问题将被转换为提案。

  ¥Issues that should be proposals will be converted to a Proposal.

• 问题将转换为问答讨论。

  ¥Questions will be converted to a Q&A Discussion.

• 可有效复现的问题将被标记为“已验证错误”，并由管理员在路线图规划会议中将其添加到路线图中。

  ¥Issues with valid reproduction will be labeled as Verified Bugs and added to the Roadmap by the Admins in the Roadmap Planning Meeting.

拉取请求选项卡

¥Pull Requests Tab

• 未经过开发流程的功能将立即关闭，并要求另行讨论。

  ¥Features that did not go through the Development Process will be immediately closed and asked to open a discussion instead.

• 没有测试用例的 Bug 修复 PR 可能会被立即关闭，并要求进行测试。（有些事情很难测试，合作者会酌情处理。）

  ¥Bug fix PRs without a test case might be closed immediately asking for a test. (Some things are hard to test, Collaborators will use discretion here.)

开发设置

¥Development Setup

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

¥Before you can contribute to the codebase, you will need to fork the repo. This will look a bit different depending on what type of contribution you are making:

以下步骤将帮助你完成为此代码库贡献更改：

¥The following steps will get you set up to contribute changes to this repo:

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

   ¥Fork the repo (click the Fork button at the top right of this page).

2. 本地克隆你的分支。

   ¥Clone your fork locally.

   # 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 文件。

   ¥Install dependencies by running pnpm. If you install using npm, unnecessary package-lock.json files will be generated.

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

   ¥Install Playwright to be able to run tests properly by running npx playwright install, or use the Visual Studio Code plugin.

5. 运行 pnpm test 来验证本地开发的所有设置是否已完成。

   ¥Verify you've got everything set up for local development by running pnpm test.

分支

¥Branches

重要提示：在 GitHub 中创建 PR 时，请确保将基础组件设置为正确的分支。

¥Important: When creating the PR in GitHub, make sure that you set the base to the correct branch.

• dev 用于代码更改。

  ¥dev is for changes to code.

• main：用于更改文档和某些模板。

  ¥main: is for changes to documentation and some templates.

你可以在 GitHub 中创建 PR 时，使用 "比较更改" 标题下方的下拉菜单设置基础配置：

¥You can set the base in GitHub when authoring the PR with the dropdown below the "Compare changes" heading:

测试

¥Tests

在本项目中，我们混合使用 jest 和 playwright 进行测试。我们在 integration 文件夹中有一套集成测试，并且包有自己的 jest 配置，然后由项目根目录中的主 jest 配置引用。

¥We use a mix of jest and playwright for our testing in this project. We have a suite of integration tests in the integration folder, and packages have their own jest configuration, which is then referenced by the primary jest config in the root of the project.

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

¥The integration tests and the primary tests can be run in parallel using npm-run-all to make the tests run as quickly and efficiently as possible. To run these two sets of tests independently, you'll need to run the individual script:

• pnpm test:primary

• pnpm test:integration

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

¥We also support watch plugins for project, file, and test filtering. To filter things down, you can use a combination of --testNamePattern, --testPathPattern, and --selectProjects. For example:

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

我们也为这些应用提供了监听模式插件。所以，你可以运行 pnpm test:primary --watch 并点击 w 来查看可用的监视命令。

¥We also have watch mode plugins for these. So, you can run pnpm test:primary --watch and hit w to see the available watch commands.

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

¥Alternatively, you can run a project completely independently by cd-ing into that project and running pnpm jest which will pick up that project's jest config.

开发工作流程

¥Development Workflow

包

¥Packages

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

¥Remix uses a monorepo to host code for multiple packages. These packages live in the packages directory.

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

¥We use pnpm workspaces to manage installation of dependencies and running various scripts. To get everything installed run pnpm install from the repo root.

构建

¥Building

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

¥Running pnpm build from the root directory will run the build. You can run the build in watch mode with pnpm watch.

在线运行

¥Playground

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

¥It's often really useful to be able to interact with a real app while developing features for apps. So you can place an app in the playground directory and the build process will automatically copy all the output to the node_modules of all the apps in the playground directory for you. It will even trigger a live reload event for you!

要生成新的 Playground，请运行：

¥To generate a new playground, run:

pnpm playground:new <?name>

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

¥Where the name of the playground is optional and defaults to playground-${Date.now()}. Then you can cd into the directory that's generated for you and run npm run dev. In another terminal window have pnpm watch running, and you're ready to work on whatever Remix features you like with live reload magic 🧙‍♂️

从 pnpm playground:new 生成的 Playground 基于 scripts/playground/template 中的模板。如果你想更改模板的任何内容，你可以在 scripts/playground/template.local 中创建一个自定义模板，即 .gitignored，这样你就可以根据自己的喜好进行自定义。

¥The playground generated from pnpm playground:new is based on a template in scripts/playground/template. If you'd like to change anything about the template, you can create a custom one in scripts/playground/template.local which is .gitignored so you can customize it to your heart's content.

测试

¥Testing

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

¥Before running the tests, you need to run a build. After you build, running pnpm test from the root directory will run every package's tests. If you want to run tests for a specific package, use pnpm test:primary --selectProjects <display-name>:

# Test all packages
pnpm test

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

代码库分支

¥Repository Branching

此代码库维护用于不同用途的独立分支。它们看起来会像这样：

¥This repo maintains separate branches for different purposes. They will look something like this:

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

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

¥There may be other branches for various features and experimentation, but all the magic happens from these branches.

夜间版本如何运作？

¥How do nightly releases work?

夜间发布将按计划从 main 分支运行操作文件。工作流程将始终使用对默认分支（以 关于 nightly action 文件的评论 表示）的最新提交，但是，它们在设置期间会检出 dev 分支，因为我们希望夜间发布从该分支进行。然后，我们会检查 git SHA 是否相同，并且只有在发生任何更改时才会每晚更新一次。

¥Nightly releases will run the action files from the main branch as scheduled workflows will always use the latest commit to the default branch, signified by this comment on the nightly action file, however, they check out the dev branch during their setup as that's where we want our nightly releases to be cut from. From there, we check if the git SHA is the same and only cut a new nightly if something has changed.

端到端测试

¥End-to-end testing

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

¥For every release of Remix (stable, experimental, nightly, and pre-releases), we will do a complete end-to-end test of Remix apps on each of our official adapters from create-remix, all the way to deploying them to production. We do this by utilizing the default templates and the CLIs for Fly, and Arc. We'll then run some simple Cypress assertions to make sure everything is running properly for both development and the deployed app.