拉取请求

¥Pull Requests

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

¥You can contribute to Material for MkDocs by making a pull request that will be reviewed by maintainers and integrated into the main repository when the changes made are approved. You can contribute bug fixes, changes to the documentation, or new functionality you have developed.

考虑拉取请求

¥Considering a pull request

在决定投入精力进行修改并创建拉取请求之前，请先讨论一下您的计划。如果您要解决的是您认为可能是 Bug 的问题，请先提交Bug 报告。如果您打算处理文档，请创建文档问题。如果您想要开发新功能，请创建变更请求。

¥Before deciding to spend effort on making changes and creating a pull request, please discuss what you intend to do. If you are responding to what you think might be a bug, please issue a bug report first. If you intend to work on documentation, create a documentation issue. If you want to work on a new feature, please create a change request.

记住给出的指导，并听取他人的建议。也许你认为并想要解决的问题有更简单的解决方案。也许你想要实现的目标已经可以通过配置或定制来实现。

¥Keep in mind the guidance given and let people advise you. It might be that there are easier solutions to the problem you perceive and want to address. It might be that what you want to achieve can already be done by configuration or customization.

了解拉取请求

¥Learning about pull requests

拉取请求 (Pull Request) 是 Git 托管服务在 Git 之上提出的一个概念。在考虑发起拉取请求之前，您应该熟悉 GitHub（我们正在使用的服务）上的文档。以下文章尤其重要：

¥Pull requests are a concept layered on top of Git by services that provide Git hosting. Before you consider making a pull request, you should familiarize yourself with the documentation on GitHub, the service we are using. The following articles are of particular importance:

1. 分支存储库

   ¥Forking a repository

2. 从分支创建拉取请求

   ¥Creating a pull request from a fork

3. 创建拉取请求

   ¥Creating a pull request

请注意，它们针对不同的操作系统和与 GitHub 交互的不同方式提供了定制的文档。我们尽力在本文档中描述 Material for MkDocs 的工作流程，但无法涵盖所有​​可能的工具组合和操作方式。在继续之前，了解拉取请求的一般概念也很重要。

¥Note that they provide tailored documentation for different operating systems and different ways of interacting with GitHub. We do our best in the documentation here to describe the process as it applies to Material for MkDocs but cannot cover all possible combinations of tools and ways of doing things. It is also important that you understand the concept of a pull-request in general before continuing.

拉取请求流程

¥Pull request process

接下来，我们将描述提交拉取请求的一般流程。我们的目标是先提供大致的概述，然后再详细介绍。

¥In the following, we describe the general process for making pull requests. The aim here is to provide the 30k ft overview before describing details later on.

准备变更并起草 PR

¥Preparing changes and draft PR

下图描述了在准备拉取请求的过程中，仓库通常会经历哪些步骤。我们将在下面讨论审核-修改流程。在考虑具体的命令之前，请务必先了解整个流程。因此，我们先介绍流程，然后再提供后续说明。

¥The diagram below describes what typically happens to repositories in the process or preparing a pull request. We will be discussing the review-revise process below. It is important that you understand the overall process first before you worry about specific commands. This is why we cover this first before providing instructions below.

sequenceDiagram
  autonumber

  participant mkdocs-material
  participant PR
  participant fork
  participant local

  mkdocs-material ->> fork: fork on GitHub
  fork ->> local: clone to local
  local ->> local: branch
  loop prepare
    loop push
      loop edit
        local ->> local: commit
      end
      local ->> fork: push
    end
    mkdocs-material ->> fork: merge in any changes
    fork ->>+ PR: create draft PR
    PR ->> PR: review your changes
  end

1. 第一步是创建 Material for MkDocs 仓库的分支，可以是mkdocs-material或mkdocs-material-insiders （仅限赞助者访问）。这将为您提供一个可以推送更改的仓库。请注意，同一仓库在任何时候都不能拥有多个分支。因此，您创建的分支将成为您拥有的分支。

2. 一旦完成，将其克隆到本地机器，以便您可以开始进行更改。

3. 所有贡献都应通过“主题分支”进行，其名称应描述正在进行的工作。这样，您可以同时进行多项工作，如果您使用的是公开版本，还可以清楚地向其他人展示代码仍在进行中。主题分支的生命周期相对较短，当您的更改被合并到代码库后，该分支就会消失。

4. 如果您打算进行任何代码更改，而不是仅仅处理文档，则需要设置开发环境。

5. 接下来是进行编辑并提交到克隆的迭代过程。请以合理的分块提交，形成一个完整的工作，而不是一次性提交所有内容。请记住，细粒度的增量提交比涉及多个文件、遍布各处的大规模更改更容易审核。尽量保持更改尽可能小且局部化，并在提交时考虑审核者。尤其要确保编写有意义的提交消息。

6. 定期将你的工作推到你的叉子上。

7. 您还应该密切关注您克隆的 Material for MkDocs 仓库中的更改。如果您的工作需要一段时间，这一点尤其重要。请尝试定期将所有并发更改合并到您的 fork 和分支中。在创建拉取请求之前，您必须至少执行一次此操作，因此，为了简化您的工作，请更频繁地执行此操作，以最大限度地降低发生更改冲突的风险。

8. 当您满意自己的更改已达到可以在草稿拉取请求中描述的状态时，就应该创建此请求。请务必引用任何促成您工作的先前讨论或问题。创建草稿是向维护者或其他人获取早期工作反馈的好方法。您可以在您认为重要的时间点明确请求审核。

9. 像审阅者一样审查你的工作，并修复迄今为止存在的任何问题。仔细检查你修改过的文件的差异。尤其要注意修改是否尽可能小，以及你是否遵循了项目中使用的通用编码风格。如果你收到了反馈，请根据需要反复进行该过程。你应该选择一些项目来测试你的更改。你一定要确保这些更改不会破坏 Material for MkDocs 文档的构建，你可以在docs文件夹中找到这些文档。你还需要确保示例代码库中的相关示例仍然能够正常构建。

最终完成

¥Finalizing

对更改满意后，即可进入下一步，完成拉取请求并请求更正式、更详细的审核。下图展示了该流程：

¥The first step is that you create a fork of the Material for MkDocs repository, either mkdocs-material or mkdocs-material-insiders (only accessible to sponsors). This provides you with a repository that you can push changes to. Note that it is not possible to have more than one fork of a given repository at any point in time. So, the fork you create will be the fork you have.

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

  activate PR
  PR ->> PR : finalize PR
  loop review
    loop discuss
      PR ->> PR: request review
      PR ->> PR: discussion
      local ->> fork: push further changes
    end
    PR ->> mkdocs-material: merge (and squash)
    deactivate PR
    fork ->> fork: delete branch
    mkdocs-material ->> fork: pull
    local ->> local: delete branch
    fork ->> local: pull
  end

1. 当您满意所做的更改足以构成维护者可以集成到代码库的贡献时，请完成拉取请求。这向所有认为工作“完成”的人发出信号，表明可以对其进行审核，以接受并集成它。

2. 请求维护者@squidfunk进行审核。

3. 维护者可能会对您的代码发表评论，您应该与他们讨论。在这样做时请记住，维护者的观点可能与您不同。他们通常会在未来几年采取更长远的眼光来维护项目，而您可能更专注于您所处理的特定问题或功能。请始终保持尊重的讨论。重要的是要注意，并非所有拉取请求都会合并到代码库中。原因可能多种多样。这项工作可能会揭示阻碍拉取请求集成的其他问题。有时，它有助于发现更好的做事方式，或表明需要一种更通用的方法。所有这些都是可以的，并且有助于项目进展，即使特定的更改最终不被接受。

4. 提交任何请求的更改，请将其提交到您的本地克隆版本，然后将其推送到您的 fork 分支。这将自动更新拉取请求。您的贡献可能需要多次迭代才能达到可接受的状态。您可以仔细阅读评论并谨慎地进行更改，以促进此过程。

5. 一旦审阅者对更改完全满意，他们就可以将更改合并到主分支（或“master”）。在此过程中，他们可能会将您的提交“压缩”成几个较小的提交，并可能编辑描述这些提交的消息。恭喜，您现在已经为该项目做出了贡献，并且应该可以在主分支中以您的名义看到更改。

6. 您现在可以删除该 fork 分支和本地仓库，下次重新开始。或者，您可以保留该仓库和本地克隆，但务必确保它们与上游仓库保持同步，以便后续工作顺利进行。我们建议您首先删除 fork 分支中使用的分支。

7. 为了确保您拥有所做的更改，请将它们从主存储库拉到您的 fork 的主分支中。

8. 类似地，从本地克隆中删除主题分支并...

9. 将更改拉到其主分支。

步骤

¥Steps

现在，我们已经概述了整个流程，下面是一些具体的说明和技巧。在描述通过拉取请求为项目做出贡献的流程时，有很多选择。下文中，我们假设您使用 Git 命令行工具。对于大多数替代方案（例如使用 IDE 或使用 GitHub 网页界面提供的功能），命令行说明的翻译应该足够简单。我们只会在真正必要的地方添加注释，以将复杂性保持在合理的范围内。

¥Once it is made, clone it to your local machine so you can start working on your changes.

分叉存储库

¥Forking the repository

要对 MkDocs 的 Material 进行更改，您首先需要在 GitHub 上 fork 一个仓库。这样，您在 GitHub 上就拥有一个可以推送更改的仓库（只有维护者和协作者才拥有原始仓库的写权限）。

¥All contributions should be made through a 'topic branch' with a name that describes the work being done. This allows you to have more than one piece of work in progress and, if you are working with the public version, also shows others clearly that the code contained is work in progress. The topic branch will be relatively short-lived and will disappear at the end, when your changes have been incorporated into the codebase.

如果您想修改公共版本的代码或文档，请为公共版本创建仓库的分支。建议您在仓库名称后附加-fork前缀，以便其他人看到该仓库时知道他们找到的是临时分支，而不是项目的原始分支或永久分支。您也可以添加描述，阐明该仓库的用途。

¥If you intend to make any code changes, as opposed to working on documentation only, you will need to set up a development environment.

如需更改仅限 Insiders 版本使用的功能，请 fork Insiders 代码库。请注意，fork 后的代码库将作为私有代码库。请遵守Insiders 计划的条款以及用于维护和开发 MkDocs 素材的 Sponsorware 方法的精神。

¥Next comes the iterative process of making edits, committing them to your clone. Please commit in sensible chunks that constitute a piece of work instead of committing everything in one go.

设置开发环境

¥Setting up a development environment

从现在开始，请按照设置开发环境的说明进行操作。这些说明将指导您完成设置环境的过程，您可以在其中进行更改并进行审查/测试。

¥Remember that fine-grained, incremental commits are much easier to review in than large changes all over the place and with many files involved. Try to keep your changes as small and localized as possible and keep the reviewer in mind when committing. In particular, make sure to write meaningful commit messages.

做出改变

¥Making changes

修改代码或文档时，请遵循项目中使用的既定风格。这样做可以提高代码可读性，也有助于审查拉取请求的人员更轻松地阅读差异。请避免进行任何大规模的风格更改，例如要求 IDE 重新格式化所有代码。

¥Push your work up to your fork regularly.

在尝试修改代码之前，务必仔细研究它，确保你完全理解它的工作原理。这不仅能帮助你解决问题，还能最大限度地降低产生意外副作用的风险。

¥You should also keep an eye on changes in the Material for MkDocs repository you cloned. This is especially important if you work takes a while. Please try and merge any concurrent changes into your fork and into your branch regularly. You must do this at least once before creating a pull request, so make your life easier and do it more often so as to minimize the risk of conflicting changes.

提交到分支

¥Committing to a branch

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

¥Once you are happy that your changes are in a state that you can describe them in a draft pull request, you should create this. Make sure to reference any previous discussions or issues that gave rise to your work. Creating a draft is a good way to get early feedback on your work from the maintainer or others. You can explicitly request reviews at points where you think this would be important.

当你想要将提交推送到你的 fork 分支时，可以使用git push -u origin <name> 。 -u参数是--set-upstream的缩写，它使新创建的分支“跟踪”你 fork 分支中具有相同<name>的分支。这意味着pull和push命令将默认在你的 fork 分支中对该分支起作用。

¥Review your work as if you were the reviewer and fix any issues with your work so far. Look critically at the diffs of the files that you have changed. In particular, pay attention to whether the changes are as small as possible and whether you have follow the general coding style used in the project. If you received feedback, iterate over the process so far as necessary.

合并并发更改

¥Merging concurrent changes

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

¥You should choose a number of projects to test your changes with. You should definitely make sure that the changes do not break the building of the documentation for Material for MkDocs, which you can find in the docs folder. You may also want to make sure that relevant examples from the examples repository still build fine.

它可能看起来像这样：

¥Once you are happy with your changes, you can move to the next step, finalizing your pull request and asking for a more formal and detailed review. The diagram below shows the process:

$ 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操作时，您需要明确指定要使用的远程仓库：

¥When you are happy that the changes you made amount to a contribution that the maintainer(s) could integrate into the codebase, finalize the pull request. This signals to everyone that consider the work 'done' and that it can be reviewed with a view to accepting and integrating it.

# making and committing some local changes
push pull upstream master

这会将master分支中的更改提取到主题分支中并合并它们。

¥Request a review from the maintainer, @squidfunk.

测试和审查变更

¥Testing and reviewing changes

在提交任何更改之前，您应该确保它们能够按预期工作，并且不会产生任何意外的副作用。您应该至少通过以下三个冒烟测试来测试它们：

¥The maintainer may make comments on your code, which you should discuss with them. Bear in mind when doing this that the maintainer may have a different point of view compared to yours. They will often take a more long-term perspective of maintaining the project in the years to come while you may be more focused on the specific issue or feature that you worked on. Please keep the discussion respectful at all times.

• MkDocs 本身的 Material 文档。如果您按照设置开发环境的说明设置并运行开发环境， mkdocs serve应该会运行并持续构建文档。请检查是否没有错误消息，最好是没有（新的）警告。

• 在代表问题的项目上进行测试，或者针对新开发的功能进行测试。如果您已经提交了错误报告并创建了最小复现，那么您可能已经拥有了这些。如果您正在开发一项新功能，那么您可能需要构建一个项目作为测试套件。它可以兼作文档，展示新功能的预期工作方式。

• 使用 Material for MkDocs 示例库中的相关示例进行测试。请注意，要一次性构建所有示例，您需要 Insiders 的项目插件，但您始终可以使用公开版本单独构建示例。

• 理想情况下，也请测试示例仓库中的示例。如果您使用的是 Material for MkDocs 的 Insiders 版本，您只需在顶层启动构建，项目插件就会为您构建所有示例。如果您使用的是公开版本，则需要单独构建每个子项目。我们理解示例库的规模正在不断扩大，您可能需要优先考虑与您更改的功能最相关的示例。

创建拉取请求

¥Creating the pull request

首先，将拉取请求创建为草稿。您可以通过 GitHub 提供的各种界面来完成此操作。使用哪个界面完全由您决定。我们不提供使用界面的具体说明，因为 GitHub 已提供所有必要的信息。

¥It is important to note that not all pull requests get incorporated into the codebase. The reasons can vary. The work may bring to light other issues that block integration of the pull request. Sometimes it helps uncover better ways of doing things or shows that a more general approach is needed. All of this is fine and helps the project progress, even if specific changes are not, ultimately, accepted.

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

¥Commits, messages, mistakes and 'squash'

删除分支

¥Deleting branches

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

¥Make any requested changes by committing them to your local clone and pushing them up to your fork. This will automatically update the pull request. It may well take a few iterations to get your contributions to an acceptable state. You can help the process along by carefully reading comments made and making changes with care.

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

¥Once the reviewer is fully satisfied with the changes, they can merge them into the main branch (or 'master'). In the process, they may 'squash' your commits together into a smaller number of commits and may edit the messages that describe them. Congratulations, you have now contributed to this project and should see the changes in the main branch under your name.

后续拉取请求

¥Subsequent Pull Requests

后续的拉取请求务必从master分支的最新历史记录开始。实现此目的的一种方法是删除之前的分支，并在下次从全新的分支开始。

¥You can now delete the fork and your local repository and start afresh again next time around. Alternatively, you can keep the repository and local clone around but it is important that you keep them in sync with the upstream repository for any subsequent work. We recommend that you start by deleting the branch you used on your fork.

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

¥To make sure you have the changes you produced, pull them from the main repository into the main branch of your fork.

注意事项

¥Dos and Don'ts

1. 不要仅仅创建未解释更改的拉取请求。

2. 在编写或修改代码之前，一定要与大家讨论您打算做什么，以便明确任何更改的理由。

3. 请链接到讨论或任何问题以提供拉取请求的上下文。

4. 如果您对任何事情不确定，请提出问题。

5. 问问自己，你所做的事情是否有利于更广泛的社区，并使 Material for MkDocs 成为更好的产品。

6. 务必问问自己，做出这些改变的成本是否与它们带来的收益成正比。一些原本合理的改变可能会增加复杂性，但收益却相对较少，可能会破坏现有行为，或者在需要进行其他更改时变得脆弱。

7. 经常合并并发更改，以尽量减少可能难以解决的冲突更改的可能性。