代码贡献

为开源项目做贡献的美妙之处在于，您可以克隆您喜欢的项目，让它在本地运行，并实时测试实验和更改！您有机会参与一个社区，同时还能体会到其中的乐趣。有关贡献文档的说明，请访问文档贡献页面。

Gatsby 采用“monorepo”模式来管理其众多依赖项，并依赖Lerna和Yarn来配置仓库，以支持主动开发和文档基础架构的更改。

Yarn 是一个包管理器，类似于npm。虽然 npm 用于通过 CLI 开发 Gatsby 站点，但贡献 Gatsby 仓库需要 Yarn，原因如下：我们使用 Yarn 的workspaces功能，这对 monorepo 非常方便。它允许我们在子文件夹中安装多个package.json文件的依赖项，从而实现更快、更轻的安装过程。

设置本地开发环境

安装 Node 和 Yarn

• 通过执行 node --version，确保您已安装 Node 的最新 LTS 版本（>= 18）。
• 安装 Yarn 包管理器。
• 通过执行 yarn --version，确保您已安装 Yarn 的 1 版本（^1）。Gatsby monorepo 尚未支持更高版本的 Yarn。

Fork、克隆并创建分支

• Fork官方 gatsbyjs/gatsby 仓库。
• 克隆您的 fork：git clone https://github.com/<your-username>/gatsby.git
• 设置仓库并安装依赖项：yarn run bootstrap
• 创建主题分支：git checkout -b topics/new-feature-name
• 从仓库根目录运行 yarn run watch，以监视包源代码的更改，并在您工作时即时编译这些更改。
  • 请注意，watch 命令可能会消耗大量资源。要将其限制为您正在处理的包，请添加一个作用域标志，例如 yarn run watch --scope={gatsby,gatsby-cli}。
  • 要只监视一个包，例如 gatsby，请运行 yarn run watch --scope=gatsby。

注意：可选地，您可以运行 git clone --depth=1 https://github.com/<your-username>/gatsby.git 来进行浅克隆（下载大小较小），而不是深度克隆。但有时在引用较旧的上游分支时，这可能会导致问题。

在示例项目中测试更改

• 安装gatsby-dev-cli

  • 确保您已安装 Gatsby Dev CLI，请运行 gatsby-dev -v。
  • 如果没有，请全局安装：yarn global add gatsby-dev-cli。
  • 运行 gatsby-dev --set-path-to-repo /path/to/my/forked/version/gatsby 将 gatsby-dev-cli 指向您的 fork。

• 在您正在测试的每个站点中运行 yarn install。

• 对于每个 Gatsby 测试站点，请在测试站点目录中运行 gatsby-dev 命令，将已构建的文件从您克隆的 Gatsby 副本复制过来。它将监视 Gatsby 包的更改并将它们复制到站点中。有关更详细的说明，请参阅gatsby-dev-cli README，并观看gatsby-dev-cli 演示视频。

  • 要仅从一个包（如 gatsby）复制文件，请运行 gatsby-dev --packages gatsby。
  • 注意：如果您打算修改直接从 gatsby 导出的包，您需要将这些包手动添加到您的测试站点中，以便它们在 package.json 中列出（例如 yarn add gatsby-link），或者使用 gatsby-dev --packages gatsby-link 明确指定它们。

• 如果您最近运行了 gatsby-dev，您的 node_modules 将与当前已发布的包不同步。为了撤销此操作，您可以删除 node_modules 目录，还原对 package.json 和 lockfiles 的任何更改，然后使用 npm install 或 yarn install 重新安装模块。或者，您可以运行

添加测试

• 为您的更改添加测试和代码。
  • 首先使用 Jest 添加单元测试。
  • 如果您想在更真实的应用程序中测试此功能，您还可以考虑添加集成测试和端到端测试。
  • 如果您不确定如何添加测试或哪种类型的测试，请在 Pull Request 的评论中提问。
• 完成后，请确保所有单元测试仍然通过：yarn test。
  • 要运行单个包的测试，可以运行：yarn jest <package-name>。
  • 要运行单个测试文件，可以运行：yarn jest <file-path>。
  • 一旦您将更改推送到 GitHub，CI 将在受控环境中运行测试，并可能在不同类型的机器（Linux vs. Windows）上发现失败。

如果您正在添加端到端测试并希望针对本地更改运行它们

• 在 monorepo 的根目录中，运行 yarn lerna run build --scope=<package-name>，其中 package-name 是包含您正在测试的更改的目录。
• 在您的特定端到端测试目录（例如 e2e-tests/themes/development-runtime）中运行 gatsby-dev。
• 在上一步运行时，打开一个新的终端窗口，并在同一端到端测试目录中运行 yarn test。

故障排除

在贡献过程的任何阶段，Gatsby 团队都很乐意提供帮助！如果您需要特定问题的帮助，可以在 GitHub 上发起讨论。或者加入我们的 Discord 服务器进行一般社区讨论和支持。

• 如果您在一段时间前完成了初始设置，现在想贡献新内容，您应该确保同步您的 fork，以获取gatsbyjs/gatsby主分支的最新更改。否则，您可能会遇到文件未找到的问题，因为它们已被重命名、移动或删除。
• 同步 fork 后，运行 yarn run bootstrap 来编译所有包。如果文件或测试依赖于构建输出（`/dist`目录中的文件），它们否则可能会失败。
• 请确保对您正在更改的包的源代码运行 yarn run watch。

如何发起 Pull Request

如果您已完成所有更改，添加了测试，并希望将您的更改贡献给 Gatsby，您可以前往如何发起 Pull Request 文档了解更多信息。

其他贡献

创建自己的插件

如果您创建了加载器或插件，我们希望您将其开源并发布到 npm。有关创建自定义插件的更多信息，请参阅插件和API 规范的文档。

贡献示例站点

Gatsby 的政策是，“使用”示例站点（例如仓库中的 examples 部分）应仅围绕核心团队维护的插件，因为否则很难保持事物的最新状态。

要贡献示例站点，建议创建您自己的 GitHub 仓库，并从您的源插件等处链接到它。您也可以创建一个 starter 项目并将其提交到starter 列表。

调试构建过程

请查看调试构建过程页面，了解如何调试 Gatsby。

反馈

在贡献过程的任何阶段，Gatsby 团队都很乐意提供帮助！如果您需要特定问题的帮助，可以在 GitHub 上发起讨论。或者加入我们的 Discord 服务器进行一般社区讨论和支持。