如何打开一个 Pull Request

贡献开源项目的一个重要部分是向项目提交更改：改进源代码或测试、更新文档内容，甚至是修复拼写错误或损坏的链接。本文档将介绍你在 Gatsby 中创建 Pull Request 所需了解的内容。

什么是 Pull Request (PR)?

如果你还不熟悉，GitHub 的开发者是这样定义 pull request 的：

Pull Request 允许你将推送到 GitHub 仓库某个分支的更改告知他人。一旦 Pull Request 被创建，你就可以与协作者讨论和评审潜在的更改，并在你的更改合并到基础分支之前添加后续的提交。

Gatsby 使用 PR 流程在将更改添加到 Gatsby 的 GitHub 仓库之前对其进行评审和测试。任何人都可以创建 Pull Request。所有贡献者都遵循相同的流程，无论这是你的第一次开源贡献还是你是 Gatsby 团队的核心成员。

当有人希望为 Gatsby 做出贡献时，他们会创建一个请求将他们的代码“拉入”仓库。根据更改的类型，PRs 被分为：

文档
代码

本指南和整个贡献文档中将提供不同类型贡献的建议。

创建 PR 前需要了解的事项

我们通常建议，如果还没有针对你想要解决的问题的 issue，请先创建 issue，然后再创建 pull request。这有助于在决定实现方案之前促进讨论。

对于某些更改，例如拼写错误修复或损坏的链接，可以直接创建一个小的 PR。

在 Gatsby 中创建 PR

对于 Gatsby 仓库中文件的任何更改，你都可以按照以下步骤进行。请务必稍后在本指南中查看有关贡献仓库不同部分（如文档更改、博客文章、Starter 或代码改进和测试）的额外提示。

要在本地针对 Gatsby 站点和项目文件测试更改，请 fork 该仓库并安装部分内容以便在本地运行。

Fork 并克隆 Gatsby 仓库.
按照你想要更改的项目部分的说明进行操作。（请参阅下面的具体部分。）
在 Git 中创建分支以隔离你的更改
一旦你的 Git 中有了想要推送到更改，添加它们并创建一个提交。有关如何构造提交的信息，请参阅管理 PR 文档。
- 使用点字符 . 将添加当前目录及其子目录中的所有未跟踪文件。
- 使用像 GitHub Desktop 或 GitX 这样的可视化工具，可以帮助你选择要提交的文件和行。
提交代码将使用 Prettier 运行自动化 linter。要手动运行 linter，请在项目的基目录中运行 npm 脚本：
在推送之前，通过修改之前的提交或通过添加新提交来提交任何 linting 更改。有关 linting 和测试的更多信息，请访问管理 PR 文档。
将你的更改推送到你的 fork，假设它已设置为 origin
要针对 Gatsby 仓库创建包含你更改的 PR，你可以使用GitHub Pull Request UI。或者，你也可以使用命令行：我们推荐使用 hub。

文档 PR

Gatsby 文档站点位于 GitHub 的 docs 目录下，包括文档和教程内容。Gatsby 仓库中还有一些示例会在文档中引用。

额外的文档 PR 步骤

对于仅限文档的更改，可以考虑使用 git checkout -b docs/some-change 或 git checkout -b docs-some-change，这将绕过 CI 流程，只运行 linting 任务。

更详细的说明可以在文档贡献页面找到。

代码变更

有关修改 Gatsby 源代码、测试、内部机制、API、包等的说明，可以在贡献文档中关于设置本地开发环境的部分找到。

为 PR 准备审核

当为monorepo准备和合并 PR 时，你需要遵循一些约定：

一个机器人会自动为你的 PR 添加 status: triage needed 标签。团队成员会移除此标签并添加适当的标签。
将 PR 标题格式化为遵循 Conventional Commits 格式（下文有更多详情）。
确保所有必需的测试都通过——如果你认为某个测试是 flaky 且你不确定，请在 pull request 中提问。
如果 PR 仍是进行中的工作，请将其置于草稿模式。
填写 PR 模板（Description, Docs, Related Issues）。

Conventional Commits 示例

在提及文件夹/文件夹结构时，假定指的是 monorepo 的根目录。

如果仅更改了/docs中的内容，例如有人修复了我们某篇文档中的拼写错误，或者你正在更新教程，那么 PR 标题应为 chore(docs): $TEXT。
如果你正在更新/.github或.circleci中的内容，那么将是 chore: $TEXT。
如果你只更新了一个包中的内容，例如/packages/gatsby-plugin-utils，那么作用域就是包名 gatsby-plugin-utils。
- 如果只更新了包内的文档或 README，标题应为 chore(gatsby-plugin-utils: $TEXT。
- 如果进行了任何其他chore更改，例如更新依赖项的补丁版本，那么是 chore(gatsby-plugin-utils): $TEXT。
- 如果你正在修复 bug：fix(gatsby-plugin-utils): $TEXT。
- 添加新功能：feat(gatsby-plugin-utils): $TEXT。
- 为包进行重大更改：BREAKING CHANGE(gatsby-plugin-utils): $TEXT——请注意，在这种情况下，你需要与团队成员协调，因为这需要更仔细的审查和特殊的发布流程。
- 改进性能：perf(gatsby-plugin-utils): $TEXT。
如果你正在更新两个包，可以这样组合：feat(gatsby,gatsby-plugin-utils): $TEXT。
如果你正在更新多个包，但更改的重点主要在一个包上（例如，你为 gatsby 添加了一个功能，并且不得不更新其他包中的一些签名），那么“一个包”的示例规则仍然适用，因此例如 feat(gatsby): $TEXT。
如果你正在更新多个包，并且没有一个明确的包与之相关，你可以跳过作用域，只执行 fix: $TEXT、feat: $TEXT 等。
如果你正在更新多个包中的依赖项，可以使用 chore(deps): $TEXT。

跟进评审和建议

PR 被发送到 Gatsby GitHub 仓库后，Gatsby 核心团队和社区可能会建议对你的 PR 引入的更改进行修改。

Gatsby 团队评审并批准社区发送的每个 PR，以确保其符合仓库的贡献指南，并寻找改进你 PR 更改的机会。

这些建议也可能被 GitHub UI 称为“请求更改”。当你的 PR 添加了更改请求时，这些更改请求以及其他所有更改请求都会显示在你的 PR 的 GitHub 页面上。从该页面，你可以使用建议 UI 来：

使用“View changes”按钮评审建议的更改。
提交建议。
讨论建议，就建议的更改提问。
将建议添加到批处理中，以便它们可以作为一个提交一起推送。

对于可能无法通过 GitHub UI 解决的建议，请记住，在 PR 合并之前，你可以继续向你的 PR 添加相关提交，这些提交也将成为该 PR 的一部分。

在所有问题都得到解决且已提交请求的更改后，你可以将对话标记为已解决。

此过程有助于 Gatsby 团队和社区在你的更改合并到 Gatsby GitHub 仓库之前对其进行改进。

使用最新的 Gatsby 更改更新你的 fork

Gatsby GitHub 仓库非常活跃，因此你很可能需要更新你的 fork 以包含最新的更改，才能合并你的代码。这需要将 Gatsby 添加为上游远程。

将 Gatsby 的仓库 URL 设置为远程源。远程名称是任意的；此示例使用 upstream。
- 注意：此语法使用 SSH 和密钥：你也可以使用 https 和你的用户名/密码。
你可以随时验证远程名称和 URL。
获取 Gatsby 的最新更改
在要更新的分支中，将 Gatsby 的任何更改合并到你的 fork 中。
- 如果有任何合并冲突，你需要解决它们以获得干净的合并。
一旦你的分支运行良好，将更改推送到你的 fork。

有关使用上游仓库的更多信息，请访问 GitHub 文档。

附加资源

立即开始构建，在 Netlify!

在 GitHub 上编辑此页面