Skip to main content

为Docusaurus做贡献

Docusaurus 是我们希望帮助使开源文档更简单的方式。我们目前有多个开源项目正在使用它，并且计划有更多。如果你有兴趣为 Docusaurus 做出贡献，希望这份文档能使贡献过程变得清晰。

开源指南网站为个人、社区和公司提供了一系列资源，帮助他们学习如何运行和贡献开源项目。无论是贡献者还是开源新手，都会发现以下指南特别有用：

行为准则​

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的问题，请使用我们的任何支持渠道，我们将尽力回答您的问题。

错误​

我们使用GitHub Issues来管理我们的公共错误。如果您想报告问题，请先查看是否已经有人提出了相关的问题。如果您确定这是一个新的、未报告的错误，您可以提交一个错误报告。

  • 一个问题，一个错误： 请在每个问题中报告一个错误。
  • 提供重现步骤：列出重现问题所需的所有步骤。阅读您的错误报告的人应该能够轻松地按照这些步骤重现您的问题。

如果你只是在修复一个错误，直接提交一个拉取请求是可以的，但我们仍然建议你提交一个问题，详细说明你正在修复的内容。这在我们不接受该特定修复但希望跟踪该问题的情况下很有帮助。

安全漏洞​

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

功能请求​

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

提案​

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

认领问题​

我们有一个适合初学者的任务列表，帮助你熟悉Docusaurus代码库并了解我们的贡献流程。这是一个很好的起点。

除了good first issue，以下标签也值得一看：

  • help wanted: 如果你在某个领域有特定的知识，处理这些问题可以让你的专业知识发光发热。
  • status: accepting pr: 社区贡献者可以随意认领这些任务。

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

或者，在打开问题时，您也可以点击“自助服务”复选框，表示您希望自己处理该问题，这也会让我们将该问题视为“已认领”。

开发​

在线一键设置贡献​

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

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

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

在 Gitpod 中打开

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

安装​

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

代码规范​

  • 最重要的是：四处看看。 匹配你在项目其余部分看到的风格。这包括格式化、文件命名、代码中的命名、文档中的命名等。
  • "有吸引力的"
  • 我们确实有Prettier（一个格式化工具）和ESLint（一个语法检查工具）来捕捉大多数风格问题。如果您在本地工作，它们应该会在每次git提交时自动修复一些问题。
  • 对于文档：不要在80个字符处换行 - 在编辑文档时配置你的编辑器以软换行。

不要过于担心样式问题——维护者会在审查你的代码时帮助你修复它们。

拉取请求​

所以您决定通过提交拉取请求将代码贡献回上游。您投入了大量的时间，我们对此表示感激。我们将尽最大努力与您合作，并确保PR得到审查。

正在处理你的第一个Pull Request吗？你可以从这个免费视频系列中学习如何操作：

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

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

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

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

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

语义化提交信息​

看看如何通过微调你的提交信息风格，让你成为一个更好的程序员。

格式：():

是可选的。如果你的更改是针对一个/两个包的，考虑添加范围。范围应该简短但可识别，例如 content-docs, theme-classic, core

各种类型的提交：

  • feat: 为最终用户提供的新API或行为。
  • fix: 为最终用户修复了一个错误。
  • docs: 对我们仓库中的网站或其他Markdown文档的更改。
  • refactor: 对生产代码的更改，不会导致行为差异，例如拆分文件、重命名内部变量、改进代码风格...
  • test: 添加缺失的测试，重构测试；不更改生产代码。
  • chore: 升级依赖项，发布新版本... 为了维护目的而定期完成的杂务。
  • misc: 任何不改变生产代码的内容，但又不是test或chore。例如，更新GitHub Actions工作流。

不过，不要对PR标题过于紧张。您的PR将被压缩合并，您提交到main分支的提交将获得PR的标题，因此分支内的提交不需要语义命名。维护者将帮助您正确设置PR标题，我们还有一个PR标签系统，它与提交消息类型不相等。您的代码比约定更重要！

示例：

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.

版本化文档​

如果您只想进行文档更改，您只需要注意版本化的文档。

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

测试计划​

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

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

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

许可​

通过为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机器人会自动更新PR状态。无需打开新的PR。

我们需要CLA来合并您的拉取请求。 虽然我们重视您的努力，并愿意等待您回来处理评论，以防您在发送拉取请求后无法联系，但如果拉取请求已准备好合并但缺少CLA且作者没有回应，将在开放后两周内关闭。如果您对CLA有进一步的问题，请与我们保持联系。

如果您当时不可用并且您的PR被关闭，一旦准备好，请随时重新打开！我们仍然很乐意审查它，帮助您完成它，并最终合并它。

重大变更​

当添加一个新的重大变更时，请在你的拉取请求中遵循此模板：

### New breaking change here

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

接下来会发生什么？​

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