拉取请求指南#
拉取请求 (PR) 是为 Matplotlibs 代码和文档做出贡献的机制。
拉取请求审阅者摘要#
笔记
如果您有提交权限，那么您就可以使用它们。 请帮助审查和合并 PR！
对贡献者保持耐心和友善。
内容主题：
组织主题：
详细指南#
文档#
每个新功能都应记录在案。如果它是一个新模块，不要忘记在 API 文档中添加一个新的 rst 文件。
每个高级绘图函数都应该
Examples在文档字符串部分有一个小示例。这应该尽可能简单地演示该方法。更复杂的示例应放入examples目录中的专用示例文件中，该文件将呈现到文档中的示例库中。构建文档并确保解决所有格式警告。
请参阅编写文档以获取我们的文档样式指南。
如果您的更改是一项主要的新功能，请将条目添加到
doc/users/whats_new.rst.如果您以向后不兼容的方式更改 API，请通过在 的相关子目录中添加文件来记录它
doc/api/next_api_changes/，可能在behavior/子目录中。
标签#
如果您有权设置标签，请使用描述性标签标记 PR。请参阅标签列表。
如果 PR 对轮子构建操作进行了更改，请添加“运行 cibuildwheel”标签以启用测试轮子。
里程碑#
根据以下规则设置里程碑：
新功能和 API 更改是下一个次要版本的里程碑
v3.X.0。下一个补丁版本的错误修复和文档字符串更改具有里程碑意义
v3.X.Y文档更改（所有 .rst 文件和示例）具有里程碑意义
v3.X-doc
如果应用了多个规则，请从上面的列表中选择第一个匹配项。
设置里程碑并不意味着或保证将为该版本合并 PR，但如果要合并它将在哪个版本中。
所有这些 PR 都应该针对主分支。里程碑标签触发具有相应分支的里程碑的自动反向移植。
合并#
文档和示例可以由第一个审阅者合并。使用阈值“这比以前好吗？” 作为审查标准。
对于代码更改（
src或中的任何内容lib），至少有两个核心开发人员（具有提交权限的人）应审查所有拉取请求。如果您是第一个审查 PR 并批准更改的人，请使用 GitHub的“批准审查” 工具将其标记为这样。如果您是后续审稿人，请批准审稿，如果您认为不需要再审稿，请合并 PR。确保所有 API 更改都记录在 的子目录之一的文件中
doc/api/next_api_changes，并且重要的新功能在doc/user/whats_new.如果 PR 已经获得正面评价，核心开发人员（例如，第一个审核者，但不一定）可能会支持该 PR 进行合并。为此，他们应该在 GitHub 和开发邮件列表上 ping 所有核心开发人员，并将 PR 标记为“与单一审查合并？” 标签。然后，其他核心开发人员可以审查 PR 并合并或拒绝它，或者只是要求在合并之前对其进行第二次审查。如果一周内没有人要求进行第二次审查，那么 PR 可以在该单一审查的基础上合并。
一个核心开发者一次应该只支持一个 PR，我们应该尽量保持合理的 PRs 流量。
不要自我合并，除非是“小”补丁来破坏 CI 或其他审阅者明确允许它（例如，“批准模 CI 传递，绿色时可能自我合并”）。
自动化测试#
每当创建或更新拉取请求时，各种自动化测试工具将在所有受支持的平台和 Python 版本上运行。
确保 Linting、GitHub Actions、AppVeyor、CircleCI 和 Azure 管道在合并之前通过（所有检查都列在拉取请求的 GitHub 页面底部）。以下是查找测试失败原因的一些提示：
如果Linting失败，您有代码样式问题，这将在拉取请求的 diff 上作为注释列出。
如果 GitHub Actions 或 AppVeyor 运行失败，请在日志中搜索
FAILURES. 下一节将包含有关失败测试的信息。如果 CircleCI 失败，您可能在文档中有一些 reStructuredText 样式问题。在 CircleCI 日志中搜索
WARNING.如果 Azure 管道因图像比较错误而失败，您可以将图像作为Azure 作业的工件找到：
单击GitHub PR 页面上检查的详细信息。
单击查看有关 Azure Pipelines 的更多详细信息以转到 Azure。
在概览页面上，相关部分中列出了工件。
Codecov 和 LGTM 目前仅供参考。他们的失败不一定是阻碍。
自动化测试中不使用tox 。支持本地测试。
如果您知道不需要测试您的更改（这非常罕见！），则可以通过在提交消息中包含或 在给定提交中跳过所有 CI。如果您知道只需要运行 CI 的子集（例如，如果您正在更改某些纯 reStructuredText 块并且只希望运行 CircleCI 以呈现结果），则也可以通过使用以下方法在单个提交上跳过单个 CI提交消息中的子字符串：
[ci skip][skip ci]GitHub 操作：
[skip actions]AppVeyor：（必须在提交的第一行）
[skip appveyor]Azure 管道：
[skip azp]圈子CI：
[skip circle]
提交次数和压缩次数#
挤压是逐案的。平衡是在贡献者的负担、保持相对干净的历史和保持可用于二等分的历史之间取得平衡。我们唯一真正严格的时候是消除二进制文件（例如多次测试图像重新生成）并删除上游合并。
不要让完美成为优秀的敌人，尤其是对于文档或示例 PR。如果您发现自己提出了许多小建议，请针对原始分支打开 PR，将更改推送到贡献者分支，或者合并 PR，然后针对上游打开新 PR。
如果你推送到贡献者分支留下评论解释你做了什么，例如“我冒昧地将一个小的清理 PR 推送到你的分支，感谢你的工作。”。如果您要对 PR 的代码或意图进行重大更改，请先与贡献者联系。
分支和反向移植#
当前分支#
当前活跃的分支是
- 主要的
当前的开发版本。未来的次要版本（v3.N.0）将从这里分支。
- v3.Nx
Matplotlib 3.N 的维护分支。未来的补丁版本将从这里分支。
- v3.NM-doc
当前版本的文档。在补丁版本中，这将被新版本的正确命名的分支替换。
拉取请求的分支选择#
通常，所有拉取请求都应针对主分支。
反向移植策略#
我们将始终向后移植到补丁发布分支（v3.Nx）：
关键错误修复（段错误、导入失败、用户无法解决的问题）
修复了对最后两个版本的回归。
其他所有内容（针对旧版本的回归、用户可以在其代码中解决的错误/api 不一致）都是根据具体情况进行的，应该是低风险的，并且需要有人来倡导和引导向后移植。
要向后移植到文档分支 ( v3.NM-doc ) 的唯一更改是对doc、examples或tutorials. 对lib或src包括仅 docstring 的任何更改不应反向移植到此分支。
自动反向移植#
我们使用 meeseeksdev 机器人根据里程碑自动向后移植合并到正确的维护分支。为了正常工作，必须在合并之前设置里程碑。如果您有提交权限，也可以在合并后通过在 PR 上留言手动触发机器人
。如果存在冲突，meeseekdevs 会通知您需要手动完成反向移植。@meeseeksdev backport to BRANCH
目标分支是通过将里程碑描述放在它自己的行上来配置的。on-merge: backport to
TARGETBRANCH
如果机器人没有按预期工作，请向 Meeseeksdev报告问题。
手动反向移植#
进行反向移植时，请复制 meeseekdev 使用的表格，
. 如果您需要手动解决冲突，请记下它们以及您如何在提交消息中解决它们。Backport PR #XXXX: TITLE OF PR
我们做一个从 main 到 v2.2.x 的反向移植，假设：
matplotlib是 matplotlib/matplotlib 存储库的只读远程分支
这TARGET_SHA是您想要反向移植的合并提交的哈希值。这可以从 GitHub PR 页面（在带有合并通知的 UI 中）或通过 git CLI 工具读取。
假设您已经有一个本地分支v2.2.x（如果没有，那么
），并且您的远程指向
被调用：git checkout -b v2.2.xhttps://github.com/matplotlib/matplotlibupstream
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>>>>>
git add lib/matplotlib/conflicted_file.py
git add lib/matplotlib/conflicted_file2.py
git cherry-pick --continue
自行决定直接推送到上游或打开 PR；一定要对v2.2.x上游分支推送或 PR，不要main！