贡献到 Docusaurus
Docusaurus 是我们希望可以帮助使开源文档更轻松的方式。我们目前有 多个使用它的开源项目，还有更多计划。如果您有兴趣贡献到 Docusaurus，希望本文档可以使贡献流程变得清晰。
开源指南 网站收集了面向想要学习如何运行和参与开源项目的个人、社区和公司的资源。无论是贡献者还是开源新手，都会发现以下指南特别有用
行为准则
Facebook 采用了一套行为准则，我们期望项目参与者遵守。请阅读 完整文本，以便了解哪些行为会被容忍，哪些行为不会。
参与
有很多方法可以为 Docusaurus 做贡献，其中许多方法不需要编写任何代码。以下是一些入门想法
- 直接开始使用 Docusaurus。浏览 入门 指南。一切按预期工作了吗？如果没有，我们一直在寻求改进。请通过 创建问题 告知我们。
- 查看 打开的问题。提供解决方法，寻求澄清或建议标签。帮助 对问题进行分类。
- 如果您发现一个想修复的问题，请 打开一个拉取请求。标记为 适合新手 的问题是入门的绝佳起点。
- 阅读 Docusaurus 文档。如果您发现任何令人困惑或可以改进的地方，您可以点击大多数文档底部的“编辑此页面”，这将带您进入 GitHub 界面以进行修改并提出更改建议。
- 查看社区成员提出的 功能请求，如果您看到想参与的功能，可以考虑打开一个拉取请求。
非常欢迎您的贡献。如果您认为需要帮助来规划您的贡献，请在 Twitter 上向 @docusaurus 发送消息，并告知我们您需要一些帮助。
加入我们的 Discord 频道
我们在 Discord 上的 #contributors 频道中讨论 Docusaurus 开发的所有事情。您也可以在 #help-and-questions 频道中帮助其他用户，这将大有帮助。
对问题和拉取请求进行分类
无需编写任何代码即可为项目做出贡献的一个很棒的方式是帮助对收到的问题和拉取请求进行分类。
- 如果您认为问题没有提供解决问题所需的所有详细信息，请索取更多信息。
- 建议 标签，这些标签可以帮助对问题进行分类。
- 标记过时或应关闭的问题。
- 索取测试计划并审查代码。
我们的开发流程
Docusaurus 使用 GitHub 作为其真实来源。核心团队将直接在那里工作。所有更改将从一开始就公开。
所有拉取请求都将由持续集成系统 GitHub Actions 检查。其中包括单元测试、端到端测试、性能测试、样式测试等等。
分支组织
Docusaurus 拥有一个主要分支 main，我们使用功能分支和部署预览来通过拉取请求交付新功能。
问题
在 创建新问题 时，请务必填写问题模板。此步骤非常重要！ 不这样做会导致您的问题无法得到及时处理。如果发生这种情况，请不要将其视为个人问题，并在收集到模板中所需的所有信息后，随时创建新的问题。
请勿将 GitHub 问题跟踪器用于提问。如果您对使用 Docusaurus 有任何疑问，请使用我们任何 支持渠道，我们将尽力回答您的问题。
错误
我们使用 GitHub 问题 来记录我们的公开错误。如果您想报告问题，请四处查看，看看是否有人已经提交过关于该问题的 issue。如果您确信这是一个新的、未报告的错误，您可以提交一个 错误报告。
- 一个 issue，一个错误：请每个 issue 只报告一个错误。
- 提供重现步骤：列出重现问题所需的所有步骤。阅读您的错误报告的人应该能够通过最小的努力按照这些步骤来重现您的问题。
如果您只是修复了错误，可以直接提交拉取请求，但我们仍然建议您提交一个 issue 来详细说明您正在修复的内容。这在以下情况下很有用：我们不接受该特定修复，但想跟踪该问题。
安全漏洞
Facebook 针对安全漏洞的披露有一个 漏洞赏金计划。请注意，请不要提交公开 issue；请遵循该页面中概述的流程。
功能请求
如果您想请求一个新功能或增强功能，但尚未考虑打开拉取请求，您可以使用 功能模板 以 详细 RFC 的形式提交 issue。或者，您可以使用 Canny 板 来进行更随意地功能请求，并在提出 RFC 之前获得足够的关注。
提案
如果您打算对现有实现进行任何非平凡的更改，我们建议使用 提案模板 提交一个 issue。这让我们可以在您投入大量精力之前对您的提案达成一致。这类问题应该很少见。
认领问题
我们有一份 适合新手的问题 列表，可以帮助您在 Docusaurus 代码库中入门，并熟悉我们的贡献流程。这是一个入门的绝佳起点。
除了 适合新手 之外，以下标签也值得一看
如果您想处理任何这些问题，只需留言“我想处理此问题”，我们将把问题分配给您并将其状态更新为“已认领”。您需要在认领后七天内发送拉取请求，以便我们仍然可以在您无法使用时将问题分配给其他人。
或者，在创建 issue 时，您也可以勾选“自助服务”复选框，以表示您想自己处理该 issue，这也会使我们看到该 issue 为“已认领”。
开发
用于贡献的在线一键式设置
您可以使用 Gitpod（一个免费的、在线的、类似 VS Code 的 IDE）来进行贡献。只需单击一下，它就会启动一个工作区（用于 Docusaurus 2），并自动
- 克隆 docusaurus 仓库。
- 安装依赖项。
- 运行
yarn start
以便您可以立即开始贡献。
您也可以尝试使用新的 github.dev 功能。当您浏览任何文件时，将域名从 github.com 更改为 github.dev 将把您的浏览器变成一个在线编辑器。您可以立即开始进行更改并发送拉取请求。
安装
- 确保您已安装 Yarn。
- 克隆存储库后，在存储库的根目录中运行
yarn install。这将安装所有依赖项以及构建所有本地包。 - 要启动开发服务器，请运行
yarn workspace website start。
代码规范
- 最重要的是：四处看看。 匹配您在项目其余部分看到的风格。这包括格式化、命名文件、在代码中命名事物、在文档中命名事物等等。
- "吸引人"
- 我们确实有 Prettier（格式化程序）和 ESLint（语法 linter）来捕获大多数样式问题。如果您在本地工作，它们应该在每次 git 提交期间自动修复一些问题。
- 对于文档：不要在 80 个字符处换行 - 在编辑文档时将编辑器配置为软换行。
一般来说，不要太担心样式 - 维护者会在审核您的代码时帮助您修复它们。
拉取请求
所以您已决定通过打开拉取请求来将代码贡献回上游。您投入了大量时间，我们对此表示感谢。我们将尽力与您合作并审查 PR。
正在处理您的第一个拉取请求？您可以从这个免费的视频系列中学习
提交拉取请求时，请确保完成以下操作
- 保持您的 PR 简短。 小的拉取请求（约 300 行差异）更容易审查，并且更有可能被合并。确保 PR 只做一件事，否则请将其拆分。
- 使用描述性的标题。 建议遵循此 提交消息样式。
- 测试您的更改。 在您的拉取请求描述中描述您的 测试计划。
- CLA。 如果您还没有，请 签署 CLA。
所有拉取请求都应针对 main 分支打开。
我们有很多集成系统运行自动化测试来防止错误。维护者也会审查您的代码并为您修复明显的问题。这些系统的职责是让您尽可能少地担心杂务。您的代码贡献比坚持任何程序更重要，尽管完成清单肯定会节省每个人的时间。
语义提交消息
看看对您的提交消息样式进行的微小更改如何让您成为更好的程序员。
格式：<type>(<scope>): <subject>
<scope> 是可选的。如果您的更改特定于一个或两个包，请考虑添加范围。范围应该简短但可识别，例如 content-docs、theme-classic、core
各种类型的提交
feat：面向最终用户的新 API 或行为。fix：面向最终用户的错误修复。docs：对我们仓库中的网站或其他 Markdown 文档的更改。refactor：对生产代码的更改，不会导致行为差异，例如拆分文件、重命名内部变量、改进代码风格...test：添加缺失的测试，重构测试；没有生产代码更改。chore：升级依赖项，发布新版本... 为维护目的定期执行的杂务。misc：任何其他不更改生产代码但不是test或chore的内容。例如更新 GitHub 操作工作流程。
不过，不要对 PR 标题感到太紧张。您的 PR 将被 squash 合并，您对 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.
版本化文档
如果您只想进行文档更改，您只需要了解版本化文档。
website/docs- 这里的文件负责 https://docusaurus.org.cn/docs/next/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来运行特定的测试。 - 试用。 我们的网站本身涵盖了各种潜在的配置案例，我们甚至有一个专门的 测试区域。不要害怕在您的 PR 中更新我们网站的配置 - 它可以帮助维护者预览效果。我们可以决定在合并和部署到生产环境时是否应该保留网站更改。
- E2E 测试。 您可以模拟代码的发布和安装以及您的最新更改。如果您需要帮助在本地测试您的更改，您可以查看有关进行 本地第三方测试 的文档。
许可
通过为 Docusaurus 贡献代码，您同意您的贡献将根据其 MIT 许可进行许可。将此复制并粘贴到您的新文件(s) 的顶部
/**
* 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。您只需要执行一次，因此如果您已经为另一个 Facebook 开源项目执行了此操作，那么您就可以继续进行。如果您是第一次提交拉取请求，Facebook GitHub 机器人将回复一个指向 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 核心团队将监控拉取请求。请通过遵循上述指南，帮助我们保持拉取请求的一致性。