拉取请求准则

拉取请求（PRs）是一种机制，用于生成Matplotlibs代码和文档。

公关作者总结

注解

• 我们重视有各种经验的人的贡献。特别是如果这是你的第一次公关不是一切都必须是完美的。我们将指导您完成公关流程。
• 尽管如此，尽量遵循下面的指导方针，以帮助公关过程快速顺利。
• 对评论者要有耐心。我们尽力快速响应，但带宽有限。如果在几天内没有任何反馈，请通过在您的公关上发表评论来ping我们。

做公关时要注意：

• Target the master branch .

• 坚持 编码指南 .

• 更新 documentation 如有必要。

• 目标是让公关尽可能“准备就绪”。这有助于加快审查进程。

• 如果您需要开发人员的帮助或反馈，可以打开未完成或正在进行的PRs。你可以把这些标记为 draft pull requests 在吉瑟布上。

• 当更新你的公关，而不是添加新的提交来修复一些东西，请考虑修改您的初始提交（s）保持历史的清洁。您可以通过以下方式实现：

  git commit --amend --no-edit
  git push [your-remote-repo] [your-branch] --force-with-lease
  

另见 贡献 如何做公关。

公关审查人员总结

注解

• 如果您有提交权限，那么您就可以使用它们。 请审阅并帮助合并PRs！
• 耐心等待 kind 有贡献者。

内容主题：

• 功能/错误修复是否合理？
• PR是否符合 编码指南 是吗？
• 是 documentation （文档字符串、示例、新增内容、API更改）是否已更新？

组织主题：

• 确保所有 automated tests 通过。
• 公关应该 target the master branch .
• 用描述性标记 labels .
• 设置 milestone .
• 密切关注 number of commits .
• 如果以上所有主题都已处理，则批准。
• Merge 如果达到足够数量的批准。

详细指南

文档

• 每一个新特性都应该被记录下来。如果是一个新模块，不要忘记向API文档中添加一个新的RST文件。
• 每个高级绘图函数在 Examples docstring的节。这应该尽可能简单地演示该方法。更复杂的示例应该放在 examples 目录，它将呈现到文档中的示例库中。
• 生成文档并确保所有格式警告都已解决。
• 见 编写文档 我们的文档样式指南。
• 如果您的更改是主要的新功能，请将条目添加到 doc/users/whats_new.rst .
• 如果您以向后不兼容的方式更改API，请将其记录在最新版本的相关文件中 doc/api/api_changes_X.Y .

标签

• 如果您有权设置标签，请使用描述性标签标记PR。见 list of labels .

里程碑

• 根据以下规则设置里程碑：

  • 新功能和API更改 在下一次小版本中有磨石吗 v3.X.0 .
  • 错误修复和docstring更改 是下一个补丁版本的里程碑 v3.X.Y
  • 文件变更 （所有.rst文件和示例）都是milestoned v3.X-doc

  如果多个规则适用，请从上面的列表中选择第一个匹配项。

  设置一个里程碑并不意味着或者保证一个PR将被合并到那个版本中，但是如果它被合并到哪个版本中。

  所有这些请购单都应以主分行为目标。里程碑标记触发一个 automatic backport 对于具有相应分支的里程碑。

合并

• 文档和示例可由第一个审阅者合并。使用阈值“这比以前好吗？”作为评审标准。

• 用于代码更改（任何 src or lib) at least two core developers (those with commit rights) should review all pull requests. If you are the first to review a PR and approve of the changes use the GitHub 'approve review' 工具来标记它。如果您是后续审阅者，请批准审阅，如果您认为不需要更多审阅，请合并公关。

  确保所有API更改都记录在最新版本的相关文件中 doc/api/api_changes_X.Y 而重要的新功能在 doc/user/whats_new .

  • 如果一个PR已经有了一个正面的评价，核心开发者（例如第一个评审者，但不一定）可能支持该PR合并。为了做到这一点，他们应该ping GitHub和dev邮件列表上的所有核心开发人员，并将PR标记为“mergewithsinglereview？”标签。其他核心开发人员可以审查PR并合并或拒绝它，或者只是请求在合并之前进行第二次审查。如果一周内没有人要求这样的第二次审查，那么可以在该次审查的基础上合并公共关系。

    一个核心开发人员一次只能支持一个PR，我们应该努力保持所支持的PR流的合理性。

• 不要自合并，除非是“小”补丁程序来解除CI中断，或者当另一个审阅者明确允许时（例如，“批准模CI传递，绿色时可能会自合并”）。

自动化测试

每当创建或更新pull请求时，各种自动化测试工具都将在所有受支持的平台和Python版本上运行。

• 确保Linting、Travis、AppVeyor、CircleCI和Azure管道在合并之前通过（所有检查都列在pull请求的GitHub页面底部）。以下是查找测试失败原因的一些提示：
  • 如果 掉毛 如果失败，则会出现代码样式问题，该问题将作为注释列在pull请求的diff上。
  • 如果Travis或AppVeyor运行失败，请在日志中搜索 FAILURES . 下一节将包含有关失败测试的信息。
  • 如果CircleCI失败，文档中可能存在一些重构文本样式的问题。在电路日志中搜索 WARNING .
  • 如果Azure管道由于图像比较错误而失败，您可以在下面找到图像 人工产品 Azure作业的名称：
    • Click 细节 在GitHub PR页面上的检查。
    • Click 查看有关Azure管道的更多详细信息 去蔚蓝。
    • 在“概述”页上 人工产品 列在本节中 相关的 .
• Codecov和LGTM目前仅供参考。他们的失败不一定是障碍。
• tox 不用于自动测试。支持本地测试。

提交和挤压的数量

• 挤压是一件一件事。平衡是在对贡献者的负担、保持一个相对干净的历史和保持一个可用于二等分的历史之间。唯一一次我们真正严格要求它是消除二进制文件（例如多个测试映像重新生成）和删除上游合并。
• 不要让完美成为好的敌人，特别是对于文档或示例prs。如果您发现自己提出了许多小建议，可以针对原始分支打开一个公关，将更改推到贡献者分支，或者合并公关，然后针对上游打开一个新的公关。
• 如果你推动一个贡献者分支留下一个评论解释你做了什么，例如“我自由地推动一个小的清理公关到你的分支，谢谢你的工作。”。如果要对pr的代码或意图进行实质性的更改，请首先与贡献者联系。

分支和端口

现有分支机构

当前的活动分支是

主人

当前开发版本。未来次要版本( v3.N.0 )将从此分支。支持Python 3.6+。

v3.N.x

matplotlib3.N的维护分支。将来的补丁版本将从此分支。支持Python 3.6+。

v3.N.M-doc

当前版本的文档。在补丁发行版上，这将替换为新发行版的一个正确命名的分支。

v2.2.x

Matplotlib 2.2 LTS的维护分支。支持Python 2.7、3.4+。

v2.2.N-doc

当前版本的文档。在补丁发行版上，这将替换为新发行版的一个正确命名的分支。

拉取请求的分支选择

通常，所有拉请求都应该以主分支为目标。

其他分支则通过 automatic 或 manual . 直接针对其他分支机构是很少有必要的特殊维护工作。

后场战略

我们将始终返回到补丁发布分支( v3.N.x ）：

• 关键错误修复（segfault、导入失败、用户无法解决的问题）
• 修复了上两个版本的回归。

其他一切（相对于旧版本的回归、用户可以在代码中解决的bug/api不一致）都是基于具体情况的，应该是低风险的，需要有人支持和引导。

唯一要后传到文档分支的更改( v3.N.M-doc )是否更改为 doc ， examples 或 tutorials . 有什么变化吗 lib 或 src 仅包含docstring的更改不应后传给此分支。

自动端口

我们使用meeseeksdev bot根据里程碑自动将合并返回到正确的维护分支。要正常工作，必须在合并之前设置里程碑。如果您有提交权限，合并后还可以通过留下消息手动触发bot。 @meeseeksdev backport to BRANCH 如果有冲突，Meeseeeekdevs会通知您需要手动执行反向端口。

目标分支通过 on-merge: backport to TARGETBRANCH 在里程碑的描述中。

如果bot不能按预期工作，请将问题报告给 Meeseeksdev .

手动端口

做反向端口时，请复制Meeseeekdev使用的表单， Backport PR #XXXX: TITLE OF PR . 如果需要手动解决冲突，请在提交消息中记录它们以及如何解决它们。

我们做了一个从master到v2.2.x的反向端口，假设：

• matplotlib 是matplotlib/matplotlib repo的只读远程分支

这个 TARGET_SHA 要回传的合并提交的哈希值。可以从GitHub PR页面（在带有合并通知的UI中）或通过gitcli工具读取。

假设您已经有一个本地分支机构 v2.2.x 如果不是，那么 git checkout -b v2.2.x 你的遥控器指向 https://github.com/matplotlib/matplotlib 被称为 upstream ：：

git fetch upstream
git checkout v2.2.x  # or include -b if you don't already have this.
git reset --hard upstream/v2.2.x
git cherry-pick -m 1 TARGET_SHA
# resolve conflicts and commit if required

有冲突的文件可以按 git status 必须用手固定（搜索 >>>>> ）一旦冲突得到解决，您就必须将文件重新添加到分支，然后继续执行cherry pick:：

git add lib/matplotlib/conflicted_file.py
git add lib/matplotlib/conflicted_file2.py
git cherry-pick --continue

使用你的判断力直接推到上游或打开一个公关；确保推或公关反对 v2.2.x 上游分支，不是 master 你说什么？