跳转至主内容
Version: 2.0.0-alpha.75

贡献

Docusaurus 2 正处于 Alpha 开发状态。 现已有早期测试者使用此软件。 我们欢迎您为下一版本的 Docusaurus 作出贡献。

开源指南网站为想要学习维护并贡献开源项目的个人、社群及企业提供了诸多资源。 初来乍到的贡献者可查看下列教程:

行为守则#

Facebook 希望所有的项目参与者都能够遵循本行为守则。 请阅读守则全文来了解允许与禁止的行为。

参与其中#

您有诸多方式可以为 Docusaurus 做出贡献,其中大多数无需您撰写甚至一行代码。 您可以从这些想法开始:

  • 开始使用 Docusaurus 2! 浏览开始上手指南。 每一步都如教程所写的能正常工作吗? 如果不能,请让我们做出改进。 请通过提交议题来让我们了解此问题。
  • 浏览 v2.0 议题。 若您有想修复的问题,请提交合并请求。 标记为 头号好议题 (Good first issue) 的都是好出发点。
  • 帮助我们改进文档。 若您发现有文档令人不解或可被改进,请提交议题。 我们还有 v2 文档的雨伞问题,总结了 v2 版文档的现在工作及未来规划。 您可以选择部分文档做出贡献。
  • 看看社群中的其他人给出的提议功能,考虑能不能提交一份合并请求来实现它。

我们十分欢迎您的贡献。 若您认为我们需要帮助您来计划贡献,请在 Twitter 上 @docusaurus 并让我们知道您需要帮助。

加入 Discord 频道#

要参与 Docusaurus 2 开发,请加入 #docusaurus-2-dev 频道。

开发流程#

Docusaurus 使用 GitHub 作为其万物根基。 核心团队将使用此平台。 自初始的任何更改均为公共可见。

当 GitHub 上的更改被批准后,我们的持续集成系统 CircleCI 将自动检查。

提交新议题#

提交新议题时,请务必确保您填写了议题模板。 这一步极为重要!否则,我们可能无法及时处理您的议题。 若此情况发生,请不要认为这是对您的人身攻击。您可以在收集完模板所需的全部信息后重新提交议题。

  • 议题,一提:请只对一个漏洞提交一个议题。
  • 提供重现步骤:列出足以重现此问题的全部步骤。 阅读您漏洞反馈的人应能根据您所提供的步骤来重现问题。

漏洞反馈#

我们使用 GitHub 议题来管理公共漏洞。 若您想反馈问题,请看看是否已有他人反馈过。 若您确定这是新的未反馈问题,请提交漏洞反馈

若您有 Docusaurus 使用问题,请联系 Docusaurus Twitter 账户 @docusaurus,我们会尽全力为您排忧解难。

您也可以提交新功能或改进请求。 若您想实现功能,请使用新功能模板创建议题。

反馈安全漏洞#

Facebook 有安全披露漏洞的奖励计划。 考虑到这点,请勿公开地反馈安全问题;请遵循链接上的流程。

贡献 Docusaurus 源码#

安装#

  1. 确保您已安装 Yarn
  2. 克隆仓库后,在其根目录运行 yarn install
  3. 要开启 Docusaurus 本地开发服务器,前往 website 目录并运行 yarn start

语义提交信息#

小改提交信息能让您成为更好的开发者。

格式:<类型>(<作用域>): <标题>

<作用域> 为可选填

示例

feat: allow overriding of webpack config^--^  ^------------^|     ||     +-> 使用现在式填写概要。|+-------> 类型:chore、docs、feat、fix、refactor、style 或 test。

提交信息类型:

  • feat: (用户新功能,而非构建脚本的新功能)
  • fix: (用户漏洞修复,而非构建代码的漏洞修复)
  • docs: (文档更改)
  • style: (格式化、补充缺少的分号等;无生产代码更改)
  • refactor: (重构生产代码,如重命名变量)
  • test: (添加缺失测试、重构测试;无生产代码更改)
  • chore: (完成其他繁琐的工作;无生产代码更改)

请使用小写,首字母请勿大写!

代码规范#

风格指南#

Prettier 能发现您代码里的多数风格问题。 您可运行 npm run prettier 来查看您的代码风格状态。

然而,Prettier 并不能识别所有存在的样式问题。

常规​​​​​#

  • 重中之重:看看别人。与他人的代码风格保持一致。 这包括格式、文件命名、变量命名及文档撰写等。
  • "优美雅致"

文档#

  • 请勿在 80 个字符处换行 - 请在编辑文档时配置您的使用自动断行功能。

合并请求#

您的首个合并请求#

写完代码后,您决定提交合并请求将内容贡献给上游。 您花费了大量时间,我们十分感谢。 我们会尽全力帮助您合并此请求。

第一次写合并请求吗? 您可从下列视频列表中学习:

如何对 GitHub 上的开源项目做出贡献

我们还有新人问题列表,助您熟悉 Docusaurus 代码库及贡献流程。 这是绝佳的开始之处。

提议更改#

若您想请求新功能或改进,但还不想创建新合并请求,您可填写新功能模板来记录议题。

若您想更改公共 API(如 docusaurus.config.js 中的内容)或是实现中的细节,我们推荐您使用新提案模板记录议题,并在标题加入 [Proposal] 标签。 这能让我们在您付出大量努力前达成一致。 此类标签应很罕见。

若您只是修复漏洞,您可立即提交合并请求,但我们仍推荐您提交议题来记录修复内容。 这有利于在我们不接受特定修复的同时记录问题。

提交合并请求#

小规模的合并请求更容易审查,且更有可能合并。 请确保每个合并请求只做一件事,否则请分开提交。 我们建议您遵循此提交信息风格

请确保在提交合并请求前完成下列各项:

  1. 派生仓库,并从 master 分支中创建您自己的分支。
  2. 在您新添加的源代码文件顶部添加版权须知。
  3. 在合并请求中描述您的测试计划。 请务必要测试您的更改
  4. 确保您的代码已格式化(yarn prettier && yarn lint)。
  5. 确保您的代码通过 Jest 测试(yarn test)。
  6. 若您尚未签署贡献者许可协议,则请进行签署

所有合并请求应针对 master 分支。

测试计划#

好的测试计划应包含运行命令及其输出,请在合并请求更改 UI 时提供截图或视频。

  • 若您修改了 API,请更新文档。

重大变更#

提出重大更改时,请确保您的合并请求符合以下模板格式:

### 重大更改
- **会影响谁**:- **如何迁移**:- **为何更改**:- **影响等级(影响人数 x 程度)**:

源代码页眉的版权声明#

将以下文本复制粘贴到您的文件顶部:

/** * 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. */

贡献者许可协议(CLA)#

为了接受您的合并请求,我们需要您填写贡献者许可协议。 您仅需要填写一次,如果您已在其他 Facebook 开源项目中填写过,则无需再次填写。 若您是第一次提交合并请求,Facebook GitHub 机器人将自动回复指向协议表格的链接。 您也可以在此处填写协议

接下来呢?#

Docusaurus 核心团队将不断监视合并请求。 请遵循上述方针来帮助所有合并请求保持一致。

授权协议#

为 Docusaurus 作出贡献,即代表您同意将您所做出的贡献以 MIT 许可协议发布。