拉取请求¶

您可以通过提交一个pull request来为Material for MkDocs做出贡献，该请求将由维护者审核，并在所做的更改获得批准后集成到主仓库中。您可以贡献错误修复、文档更改或您开发的新功能。

考虑提交拉取请求

在决定花费精力进行更改并创建拉取请求之前，请先讨论您打算做的事情。如果您认为可能存在错误，请先提交一个bug report。如果您打算处理文档，请创建一个documentation issue。如果您想开发新功能，请创建一个change request。

请记住所提供的指导，并让人们给您建议。您所感知并想要解决的问题可能有更简单的解决方案。您想要实现的目标可能已经可以通过配置或customization来完成。

了解拉取请求¶

拉取请求是由提供Git托管的服务在Git之上构建的概念。在考虑提交拉取请求之前，您应该熟悉我们使用的服务GitHub上的文档。以下文章特别重要：

请注意，它们为不同的操作系统和与GitHub交互的不同方式提供了量身定制的文档。我们在这里的文档尽力描述适用于Material for MkDocs的过程，但无法涵盖所有可能的工具组合和操作方式。在继续之前，理解拉取请求的概念也很重要。

拉取请求流程¶

在下面，我们描述了提交拉取请求的一般过程。这里的目的是提供一个30,000英尺的概述，然后再详细描述后面的细节。

准备更改和草稿PR¶

下图描述了在准备拉取请求的过程中，仓库通常会发生什么。我们将在下面讨论审查-修订过程。首先了解整体过程很重要，然后再担心具体命令。这就是为什么我们首先覆盖这个内容，然后在下面提供指令。

sequenceDiagram
  autonumber

  participant mkdocs-material
  participant PR
  participant fork
  participant local

  mkdocs-material ->> fork: 在GitHub上fork
  fork ->> local: 克隆到本地
  local ->> local: 创建分支
  loop 准备
    loop 推送
      loop 编辑
        local ->> local: 提交
      end
      local ->> fork: 推送
    end
    mkdocs-material ->> fork: 合并任何更改
    fork ->>+ PR: 创建草稿PR
    PR ->> PR: 审查您的更改
  end

第一步是您创建Material for MkDocs仓库的一个fork。这为您提供了一个可以推送更改的仓库。请注意，在任何时候都不可能有超过一个给定仓库的fork。因此，您创建的fork将是您唯一的fork。
创建后，将其克隆到您的本地计算机，以便您可以开始处理更改。
所有贡献都应通过一个“主题分支”进行，该分支的名称描述正在进行的工作。这使您可以同时进行多个工作，并且如果您正在处理公共版本，也能清楚地向其他人展示所包含的代码是正在进行的工作。主题分支相对短暂，并将在您的更改被合并到代码库后消失。
如果您打算进行任何代码更改，而不仅仅是处理文档，您需要设置开发环境。
接下来是进行编辑、提交到您的克隆的迭代过程。请以合理的块提交，构成一项工作，而不是一次性提交所有内容。

请记住，细粒度的增量提交比涉及许多文件的大更改更容易审查。在提交时尽量保持更改尽可能小且局部，并考虑审阅者的感受。特别是，确保编写有意义的提交消息。
定期将您的工作推送到您的fork。
您还应该关注您克隆的Material for MkDocs仓库中的更改。如果您的工作需要一些时间，这一点尤其重要。请尽量定期将任何并发更改合并到您的fork和分支中。在创建拉取请求之前，您*必须*至少执行一次此操作，因此请更频繁地执行此操作，以最小化冲突更改的风险。
一旦您对您的更改感到满意，并且可以在*草稿*拉取请求中描述它们，您应该创建这个请求。确保引用任何引发您工作的先前讨论或问题。创建草稿是获取维护者或其他人对您工作的*早期*反馈的好方法。您可以在认为重要的地方明确请求审查。
像审阅者一样审查您的工作，并修复到目前为止您工作的任何问题。批判性地查看您所更改的文件的差异。特别注意更改是否尽可能小，以及您是否遵循了项目中使用的一般编码风格。如果您收到了反馈，请根据需要迭代整个过程。

您应该选择一些项目来测试您的更改。您应该确保更改不会破坏Material for MkDocs的文档构建，您可以在docs文件夹中找到该文档。您可能还想确保来自examples repository的相关示例仍然可以正常构建。

完成¶

一旦您对更改感到满意，您可以进入下一步，完成您的拉取请求并请求更正式和详细的审查。下图显示了该过程：

sequenceDiagram
  autonumber
  participant mkdocs-material
  participant PR
  participant fork
  participant local

  activate PR
  PR ->> PR : 完成PR
  loop 审查
    loop 讨论
      PR ->> PR: 请求审查
      PR ->> PR: 讨论
      local ->> fork: 推送进一步更改
    end
    PR ->> mkdocs-material: 合并（并压缩）
    deactivate PR
    fork ->> fork: 删除分支
    mkdocs-material ->> fork: 拉取
    local ->> local: 删除分支
    fork ->> local: 拉取
  end

当您满意所做的更改足以让维护者将其集成到代码库中时，请完成拉取请求。这向所有人发出信号，表明您认为工作“完成”，可以进行审查，以便接受和集成。
请求维护者@squidfunk进行审查。
维护者可能会对您的代码提出意见，您应与他们讨论。在这样做时，请记住，维护者可能与您有不同的观点。他们通常会从长期维护项目的角度来看待未来的几年，而您可能更关注您所处理的特定问题或功能。请始终保持讨论的尊重。

重要的是要注意，并非所有拉取请求都会被集成到代码库中。原因可能各不相同。工作可能会暴露出其他问题，从而阻碍拉取请求的集成。有时，这有助于发现更好的解决方案，或表明需要更通用的方法。所有这些都是好的，有助于项目的进步，即使具体的更改最终没有被接受。
按照要求进行更改，通过将其提交到您的本地克隆并推送到您的fork来实现。这将自动更新拉取请求。您可能需要经过几次迭代才能使您的贡献达到可接受的状态。您可以通过仔细阅读所做的评论并小心进行更改来帮助这个过程。
一旦审阅者对更改完全满意，他们可以将其合并到主分支（或“master”）中。在此过程中，他们可能会将您的提交压缩到较少的提交中，并可能编辑描述它们的消息。恭喜您，您现在已经为这个项目做出了贡献，并应该在主分支下看到您的更改。
现在，您可以删除fork和本地仓库，并在下次开始时重新开始。或者，您可以保留该仓库和本地克隆，但重要的是要确保在后续工作中与上游仓库保持同步。我们建议您首先删除您在fork上使用的分支。
为确保您拥有所做的更改，请从主仓库拉取它们到您的fork的主分支中。
同样，从您的本地克隆中删除主题分支，并...
将更改拉取到其主分支中。

步骤¶

现在整体流程已概述，以下是具体的指令和提示。在通过拉取请求为项目做出贡献时，有许多选择需要做出。在下面，我们假设您正在使用Git命令行工具。对于大多数替代方案（例如使用IDE或通过GitHub网页界面提供的功能），从命令行指令的转换应该足够简单。我们只会在确实必要的地方添加说明，以保持复杂性在合理范围内。

Forking the repository¶

要对Material for MkDocs进行更改，您首先需要在GitHub上fork其一个仓库。这是为了让您在GitHub上拥有一个可以推送更改的仓库（只有维护者和合作者对原始仓库具有写入权限）。

如果您想对代码或文档进行更改，请fork该repository。最好通过附加-fork来更改仓库的名称，以便遇到它的人知道他们发现的是一个临时fork，而不是原始或永久的项目fork。您可能还想添加一个描述，以澄清该仓库的用途。

设置开发环境¶

从这一点开始，请遵循设置开发环境的说明。它们将指导您完成设置一个可以进行更改并进行审查/测试的环境的过程。

进行更改¶

当您对代码或文档进行更改时，请遵循项目中使用的既定风格。这样可以提高可读性，并有助于使差异更容易被审查者阅读。避免进行任何大规模的样式更改，例如要求您的IDE重新格式化所有代码。

在尝试更改之前，仔细研究您正在修改的代码，以确保您完全理解其工作原理。这不仅有助于您解决要处理的问题，还可以最小化产生意外副作用的风险。

提交到分支¶

拉取请求的开发最好在与master分支分开的主题分支中进行。使用git switch -c <name>创建一个新的本地分支，并将更改提交到该分支。

当您想将提交推送到您的fork时，可以使用git push -u origin <name>。-u参数是--set-upstream的简写，这使得新创建的分支“跟踪”您fork中同名的分支。这意味着pull和push命令将默认作用于您fork中的该分支。

合并并发更改¶

如果您所做的工作需要一些时间，那么在您工作期间，主仓库可能会进行更改。将原始Material for MkDocs仓库设置为您本地克隆的upstream仓库可能是个好主意。

这可能看起来像这样：

$ git remote -v
origin  git@github.com:<your_username>/mkdocs-material-fork.git (fetch)
origin  git@github.com:<your_username>/mkdocs-material-fork.git (push)
$ git remote add upstream https://github.com/squidfunk/mkdocs-material.git
$ git remote -v
origin  git@github.com:alexvoss/mkdocs-material-fork.git (fetch)
origin  git@github.com:alexvoss/mkdocs-material-fork.git (push)
upstream    https://github.com/squidfunk/mkdocs-material.git (fetch)
upstream    https://github.com/squidfunk/mkdocs-material.git (push)

完成此操作后，您可以直接从上游仓库将任何并发更改拉取到您的克隆中，并在其中进行必要的合并，然后将它们推送到您的fork。在执行pull时，您需要明确指定要使用哪个远程仓库：

# 进行并提交一些本地更改
push pull upstream master

这将从master分支获取更改并合并到您的主题分支中。

测试和审查更改¶

在提交任何更改之前，您应确保它们按预期工作，并且不会产生任何意外副作用。您应该至少在这三个smoke tests上进行测试：

Material for MkDocs本身的文档。如果您按照设置开发环境的说明设置并运行开发环境，mkdocs serve应该正在运行并持续构建文档。检查是否没有错误消息，理想情况下没有（新的）警告。
在代表问题的项目上进行测试，或为新开发的功能进行测试。如果您已经提交了bug报告并创建了一个minimal reproduction，那么您可能已经拥有这个。如果您正在开发新功能，您可能需要构建一个项目作为测试套件。它也可以作为文档，展示您的新功能应如何工作。
使用来自Material for MkDocs Examples仓库的相关示例进行测试。
理想情况下，还要测试examples repository中的示例。

创建拉取请求¶

最初，创建拉取请求**作为草稿**。您可以通过GitHub提供的各种接口来完成此操作。您使用哪个接口完全取决于您自己。我们不提供使用接口的具体说明，因为GitHub提供了所有必要的信息。

提交、消息、错误和“压缩”¶

删除分支¶

一旦拉取请求已合并到Material for MkDocs仓库的主分支中，您应从GitHub上的fork和计算机上的本地克隆中删除该分支。这可以避免对开发状态的混淆。

首先，使用git switch master切换回master分支，然后使用git branch -d <name>删除用于PR的分支。

后续拉取请求¶

重要的是，后续拉取请求应从master分支的最新历史记录开始。实现这一点的一种方法是删除fork，并在下次开始时从头开始。

如果您更频繁地为Material for MkDocs做出贡献，或者恰好连续进行两个或多个拉取请求，您也可以确保同步您的fork（使用GitHub UI），并将其拉取到您的本地仓库中。因此，只需删除您创建的主题分支（在本地和您的fork中），然后从主仓库的master分支拉取到您的master分支中，再开始新的拉取请求。

注意事项¶

**不要**仅仅创建一个未解释的拉取请求。
**请**与讨论中的人讨论您打算做的事情，以便在编写或修改代码之前，任何更改的理由都清晰明了。
**请**链接到讨论或任何问题，以提供拉取请求的上下文。
**请**在不确定任何事情时提出问题。
**请**问问自己您所做的事情是否对更广泛的社区有益，并使Material for MkDocs成为更好的产品。
**请**问问自己进行更改的成本与它们将带来的好处是否成正比。一些合理的更改可能会增加复杂性而收益较少，可能会破坏现有行为，或者在需要进行其他更改时可能会变得脆弱。
**请**频繁合并并发更改，以最小化可能难以解决的冲突更改的机会。