为 Docusaurus 贡献

Docusaurus 是我们希望帮助简化开源文档的方式。我们目前有多个开源项目正在使用它，还有更多计划中的项目。如果您有兴趣为 Docusaurus 贡献，希望本文档能让贡献流程变得清晰明了。

Open Source Guides 网站收集了希望学习如何运营和贡献开源项目的个人、社区和公司的资源。贡献者和开源新手都会发现以下指南特别有用：

• 如何为开源项目贡献
• 构建友好社区

行为准则

Meta 采纳了一份行为准则，我们期望项目参与者遵守该准则。请阅读全文，以便您了解哪些行为被允许，哪些不被允许。

参与其中

有许多方法可以为 Docusaurus 贡献，其中许多方式不涉及编写任何代码。这里有一些入门想法：

• 只需开始使用 Docusaurus。通读入门指南。一切都按预期运行吗？如果没有，我们一直在寻求改进。通过提出问题告诉我们。
• 查看开放的问题。提供变通方案，寻求澄清，或建议标签。协助分类问题。
• 如果您发现想要解决的问题，请提交拉取请求。标记为Good first issue（适合首次贡献）的问题是很好的入门点。
• 通读Docusaurus 文档。如果您发现任何令人困惑或可以改进的地方，可以在大多数文档底部点击“编辑此页面”，这将带您进入 GitHub 界面以进行和提出更改。
• 查看社区中其他人请求的功能，如果您看到想做的工作，可以考虑提交拉取请求。

非常欢迎您的贡献。如果您认为在规划贡献时需要帮助，请在 X 上 @docusaurus 联系我们，让我们知道您需要一些帮助。

加入我们的 Discord 频道

我们在 Discord 上有 #contributors 频道，用于讨论 Docusaurus 开发相关的所有事情。您也可以通过在 #help-and-questions 频道帮助其他用户来提供巨大帮助。

分类问题和拉取请求

一种无需编写任何代码即可为项目贡献的好方法是，帮助对传入的问题和拉取请求进行分类。

• 如果您认为问题没有提供解决所需的所有详细信息，请要求提供更多信息。
• 建议有助于对问题进行分类的标签。
• 标记过时或应关闭的问题。
• 请求测试计划并审查代码。

我们的开发流程

Docusaurus 使用 GitHub 作为其单一真相来源。核心团队将直接在那里工作。所有更改从一开始就将是公开的。

所有拉取请求将由持续集成系统 GitHub Actions 进行检查。包括单元测试、端到端测试、性能测试、样式测试等等。

分支组织

Docusaurus 有一个主分支 main，我们使用带有部署预览的功能分支通过拉取请求交付新功能。

问题

当提出新问题时，请务必填写问题模板。这一步非常重要！ 不这样做可能导致您的问题无法及时处理。如果发生这种情况，请不要介意，一旦您收集了模板所需的所有信息，请随时提出新问题。

请不要使用 GitHub 问题跟踪器来提问。 如果您对使用 Docusaurus 有疑问，请使用我们的任一支持渠道，我们将尽力回答您的问题。

Bug

我们使用GitHub Issues 来跟踪公开 Bug。如果您想报告问题，请先查看是否有人已提出相关问题。如果您确定这是一个新的、未报告的 Bug，您可以提交一份Bug 报告。

• 一个问题，一个 Bug： 请每个问题只报告一个 Bug。
• 提供复现步骤： 列出重现该问题所需的所有步骤。阅读您 Bug 报告的人应该能够轻松地遵循这些步骤来重现您的问题。

如果您只是修复一个 Bug，可以直接提交拉取请求，但我们仍建议提出一个问题，详细说明您正在修复什么。这有助于我们追踪该问题，以防我们不接受该特定修复。

安全 Bug

Meta 有一个Bug 赏金计划，用于安全披露安全 Bug。请注意，不要公开提交问题；请按照该页面上概述的流程进行操作。

功能请求

如果您想请求新功能或增强功能，但尚未考虑提交拉取请求，您可以使用功能模板以详细 RFC 的形式提出问题。或者，您可以使用Canny 论坛进行更随意的功能请求，并在提出 RFC 之前获得足够的关注度。

提案

如果您打算对现有实现进行任何非微小的更改，我们建议您使用提案模板提出问题。这使我们能够在您投入大量精力之前就您的提案达成一致。这类问题应该很少见。

认领问题

我们有一份新手友好的问题列表，旨在帮助您熟悉 Docusaurus 代码库和我们的贡献流程。这是很好的入门点。

除了 good first issue 之外，以下标签也值得关注：

• help wanted：如果您在某个领域有特定知识，解决这些问题可以发挥您的专长。
• status: accepting pr：社区贡献者可以随意认领其中任何一个。

如果您想处理这些问题中的任何一个，只需留言“我想处理这个”，我们就会将该问题分配给您，并将问题状态更新为“已认领”。您需要在七天内发送拉取请求，以便在您无法处理时，我们仍可以将问题委托给其他人。

另外，在提出问题时，您也可以勾选“自助服务”复选框，表明您想自己处理该问题，这也会使我们认为该问题“已认领”。

开发

在线一键式贡献设置

您可以使用 Gitpod（一个免费的在线类 VS Code IDE）进行贡献。只需点击一下，它将启动一个工作区（适用于 Docusaurus 2），并自动：

• 克隆 Docusaurus 仓库。
• 安装依赖。
• 运行 yarn start

这样您就可以立即开始贡献。

您还可以尝试使用新的 github.dev 功能。当您浏览任何文件时，将域名从 github.com 更改为 github.dev 会将您的浏览器变成一个在线编辑器。您可以立即开始更改并发送拉取请求。

安装

1. 请确保已安装 Yarn。
2. 克隆仓库后，在仓库根目录运行 yarn install。这将安装所有依赖项并构建所有本地包。
3. 要启动开发服务器，请运行 yarn workspace website start。

代码规范

• 最重要的是：环顾四周。 与项目中其他地方使用的风格保持一致。这包括格式化、文件命名、代码中的命名、文档中的命名等。
• 美观
• 我们有 Prettier（格式化工具）和 ESLint（语法检查工具）来捕获大多数风格问题。如果您在本地工作，它们应该在每次 git 提交时自动修复一些问题。
• 对于文档：不要将行限制在 80 个字符内——在编辑文档时将您的编辑器配置为软换行。

总的来说，不要太担心风格问题——维护者在审查您的代码时会帮助您修复它们。

拉取请求

您已决定通过提交拉取请求来向上游贡献代码。您投入了大量时间，我们对此表示感谢。我们将尽力与您合作，并审查您的拉取请求。

正在处理您的第一个拉取请求？您可以从这个免费视频系列中学习如何操作：

如何在 GitHub 上为开源项目贡献

提交拉取请求时，请确保完成以下事项：

1. 保持您的拉取请求（PR）精简。 小的拉取请求（约 300 行差异）更容易审查，也更有可能被合并。请确保您的 PR 只做一件事，否则请将其拆分。
2. 使用描述性标题。 建议遵循此提交消息风格。
3. 测试您的更改。 在您的拉取请求描述中说明您的测试计划。
4. CLA。 如果您尚未签署，请签署贡献者许可协议。

所有拉取请求都应该针对 main 分支打开。

我们有许多集成系统运行自动化测试以防止错误。维护者还会审查您的代码并为您修复明显的问题。这些系统的职责是让您尽可能少地担心琐事。您的代码贡献比遵循任何程序更重要，尽管完成清单肯定会节省每个人的时间。

语义化提交信息

了解提交消息风格的微小改变如何让您成为更好的程序员。

格式：<type>(<scope>): <subject>

<scope> 是可选的。如果您的更改特定于一两个包，请考虑添加作用域。作用域应该简短但可识别，例如 content-docs、theme-classic、core

各种提交类型

• feat：面向最终用户的新 API 或行为。
• fix：面向最终用户的 Bug 修复。
• docs：对网站或仓库中其他 Markdown 文档的更改。
• refactor：对生产代码的更改，但没有行为差异，例如拆分文件、重命名内部变量、改进代码风格...
• test：添加缺失测试，重构测试；不改变生产代码。
• chore：升级依赖，发布新版本... 为维护目的而定期进行的杂务。
• misc：不改变生产代码，但也不是 test 或 chore 的任何其他内容。例如更新 GitHub Actions 工作流。

但是，请不要对拉取请求标题过于纠结。您的拉取请求将被合并（squash-merged），并且您提交到 main 分支的提交将获得您的拉取请求标题，因此分支内的提交无需语义化命名。维护者会帮助您正确设置拉取请求标题，我们也有一个与提交消息类型不完全相同的拉取请求标签系统。您的代码比约定更重要！

示例

feat(core): allow overriding of webpack config
^--^^----^  ^------------^
|   |       |
|   |       +-> Summary in present tense. Use lower case not title case!
|   |
|   +-> The package(s) that this change affected.
|
+-------> Type: see above for the list we use.

版本化文档

如果您只想更改文档，只需了解版本化文档即可。

• website/docs - 此处的文件负责 https://docusaurus.org.cn/docs/installation 上的“下一”版本。
• website/versioned_docs/version-X.Y.Z - 这些是 https://docusaurus.org.cn/docs/X.Y.Z/installation 上的 X.Y.Z 版本的文档。

除非您确定有必要，否则不要编辑 versioned_docs/ 或 versioned_sidebars/ 内自动生成的文件。例如，有关新功能的信息不应记录在版本化文档中。对旧版本所做的编辑不会传播到新版本的文档。

测试计划

一个好的测试计划应包含您运行的确切命令及其输出，如果拉取请求更改了 UI，还应提供截图或视频。如果您更改了 API，请更新文档。

测试已集成到我们的持续集成系统中，因此您不总是需要运行本地测试。但是，对于重要的代码更改，如果您能首先在本地进行详尽测试，以确保您的 PR 状态良好，这将节省您和维护者的时间。测试有许多类型：

• 构建和类型检查。 我们的代码库使用 TypeScript，这可以确保您的代码一致并及早发现一些明显错误。
• 单元测试。 我们使用 Jest 对 API 端点行为进行单元测试。您可以在根目录运行 yarn test 来运行所有测试，或运行 yarn test path/to/your/file.test.ts 来运行特定测试。
• 内部测试（Dogfooding）。 我们的网站本身涵盖了各种潜在的配置情况，我们甚至有一个专门的测试区域。在您的拉取请求中不要害怕更新我们网站的配置——这可以帮助维护者预览效果。我们可以在合并并部署到生产环境时决定是否保留网站更改。
• 端到端测试（E2E tests）。 您可以使用您的新更改模拟代码的分发和安装。如果您在本地测试更改时需要帮助，可以查看关于进行本地第三方测试的文档。

许可

通过为 Docusaurus 贡献，您同意您的贡献将根据其 MIT 许可进行许可。请将以下内容复制粘贴到您新文件的顶部：

/**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */

这也可以通过 header/header ESLint 规则自动修复。

贡献者许可协议 (CLA)

为了接受您的拉取请求，我们需要您提交一份 CLA。您只需执行此操作一次，因此如果您已经为另一个 Meta 开源项目完成过此操作，则无需再次操作。如果您是首次提交拉取请求，Meta GitHub Bot 将回复 CLA 表单的链接。您也可以在此处完成您的 CLA。

签署 CLA 后，CLA Bot 将自动更新 PR 状态。无需打开新的 PR。

我们需要 CLA 才能合并您的拉取请求。 尽管我们重视您的努力，并愿意在您发送拉取请求后因故无法处理时等待您回来解决审查意见，但对于已准备好合并但缺少 CLA 且作者没有回应的拉取请求，将在开启后两周内关闭。如果您对 CLA 有进一步疑问，请与我们保持联系。

如果您因故无法处理而您的拉取请求被关闭，请在准备好后随时重新打开！我们仍然乐意审查它，帮助您完成它，并最终合并它。

破坏性变更

添加新的破坏性变更时，请在您的拉取请求中遵循此模板：

### New breaking change here

- **Who does this affect**:
- **How to migrate**:
- **Why make this breaking change**:
- **Severity (number of people affected x effort)**:

接下来会发生什么？

Docusaurus 核心团队将监控拉取请求。请遵循以上指南，保持拉取请求的一致性，以帮助我们。