Pull request 指南#

Pull requests (PRs) on GitHub 是为 Matplotlib 的代码和文档做贡献的机制.

我们重视来自所有经验水平的人的贡献.特别是,如果这是你的第一个 PR,不一定所有事情都必须是完美的.我们将指导你完成 PR 流程.尽管如此,请尽可能遵循我们的指南,以帮助使 PR 流程快速而顺利.如果你的 pull request 不完整或正在进行中,请将其标记为 GitHub 上的 draft pull requests ,并说明开发人员的哪些反馈会有帮助.

请对审阅者保持耐心.我们尽力快速响应,但我们的带宽有限.如果在几天内没有收到反馈,请通过在你的 PR 上发表评论或在 communication channel 上联系我们来 ping 我们.

Pull request 作者须知#

我们建议你在提交 pull request 之前,检查你的贡献是否符合以下准则:

  • 更改,包括新功能和 bug 修复,应该有良好的测试覆盖率. 更多细节请参考 测试 .

  • 必要时更新 documentation .

  • 所有公共方法都应具有信息丰富的文档字符串,并在适当的时候提供示例用法. 使用 docstring standards .

  • 对于高级绘图函数,请考虑将一个小例子添加到 examples gallery .

  • 如果你添加一个主要的新功能或以向后不兼容的方式更改 API,请按照 API 指南 中的描述进行记录.

  • 代码应遵循我们的惯例,如我们的 编码规范 中所记录的那样.

  • 在添加或更改公共函数签名时,请添加 type hints .

  • 在添加关键字参数时,请参阅我们的 关键字参数处理 指南.

在 Github 上打开 pull request 时,请确保:

  • 更改是在 feature branch 上进行的.

  • pre-commit 检查拼写,格式等是否通过

  • Pull request 的目标是 main branch

  • 如果你的 pull request 解决了一个 issue,请使用标题来描述该 issue(例如 "Add ability to plot timedeltas"),并在 pull request 描述中提及 issue 编号,以确保创建到原始 issue 的链接(例如 "Closes #8869" 或 "Fixes #8869").这将确保在你的 PR 合并后,提到的原始 issue 将自动关闭.有关更多详细信息,请参阅 linking an issue and pull request .

  • 自动化测试 通过

有关创建和管理 pull request 的指南,请参阅我们的 contributing 和 pull request workflow 指南.

Pull request 审阅者须知#

请帮助审查和合并 PR!

如果你有提交权限,那么你被信任可以使用它们. 请对贡献者保持耐心和 kind .

在审查时,请确保 pull request 在合并之前满足以下要求:

内容#

  • 这个特性/缺陷修复是否合理?

  • 此PR是否符合 编码规范 ?

  • Is the documentation (docstrings, examples, what's new, API changes) updated?

  • 这种改变是否纯粹是样式上的?通常,当不属于其他非样式工作时,不鼓励这种更改,因为它模糊了代码功能更改的git历史记录.作为更大的重构/重写的一部分,重排方法或文档字符串是可以接受的.

工作流程#

详细指南#

文档#

  • 每个新功能都应该被记录.如果它是一个新的模块,不要忘记在API文档中添加一个新的rst文件.

  • 每个高级绘图函数都应该在文档字符串的 Examples 部分中有一个小例子.这应该尽可能简单,以演示该方法.更复杂的示例应该放在 examples 目录中的专用示例文件中,该文件将被呈现到文档中的示例库中.

  • 构建文档,并确保所有格式警告都已解决.

  • 有关我们的文档风格指南,请参见 编写文档 .

标签#

  • 如果您有权设置标签,请使用描述性标签标记PR.请参阅 list of labels .

  • 如果PR更改了wheel构建Action,则添加"Run cibuildwheel"标签以启用测试wheels.

里程碑#

根据以下准则设置里程碑:

  • 新特性和API更改的里程碑是下一个中版本 v3.N.0 .

  • Bug修复,已发布代码的测试和文档字符串更改可以设置为下一个微版本 v3.N.M 的里程碑.

  • 文档更改(仅.rst文件和示例)可以设置为 v3.N-doc 的里程碑.

如果适用多个规则,请从以上列表中选择第一个匹配项. 有关应该或不应该向后移植的内容的详细指南,请参见 反向移植策略 .

里程碑标记着一个PR应该进入的版本.它说明了意图,但由于发布计划或对PR范围和成熟度的重新评估,可以进行更改.

所有Pull Request都应以main分支为目标.里程碑标签会触发具有相应分支的里程碑的 automatic backport .

合并#

作为指导原则,我们要求在合并pull request之前,必须得到核心开发人员(具有提交权限的人员)的两个 approvals .这种两人观察策略应确保项目方向一致,并防止意外错误.如果更改不是根本性的,并且将来可以随时轻松还原,则允许仅获得一个批准就进行合并.

由此得出一些明确的规则:

  • 文档和示例可以仅获得一个批准就进行合并. 使用"这比以前更好吗?"的阈值作为审查标准.

  • 较小的基础结构更新,例如临时固定损坏的依赖项或对CI配置的小更改,可以仅获得一个批准就进行合并.

  • 代码更改( src 或 lib 中的任何内容)必须获得两次批准.

    确保所有API更改都记录在 doc/api/next_api_changes 的子目录之一的文件中,并且重要的的新特性在 doc/user/whats_new 中都有一个条目.

    • 如果PR已经有了一个正面的评价,那么一个核心开发人员(例如,第一个评价者,但不一定)可以支持该PR进行合并.为了做到这一点,他们应该在GitHub和dev邮件列表上ping所有核心开发人员,并用"Merge with single review?"标签标记PR. 其他核心开发人员可以审查PR并合并或拒绝PR,或者只是要求在合并前进行第二次审查.如果在一周内没有人要求进行这样的第二次审查,那么PR就可以基于该单一审查合并.

      核心开发者一次只能支持一个PR,我们应该尽量保持所支持的PR的合理流程.

在给出最后一个必需的批准后,批准的作者应该合并PR.PR作者不应该自行合并,除非另一个审查者明确允许(例如,"批准取决于CI通过,如果通过可以自行合并",或者"接受或不接受这些评论.您可以自行合并.").

自动化测试#

在合并之前,PR应该通过 自动化测试 .如果您不确定为什么测试失败,请在PR或我们的 官方沟通渠道 中提问.

提交次数和压缩#

  • 压缩是具体情况具体分析的.平衡点在于贡献者的负担,保持相对清晰的历史记录以及保持可用于二分查找的历史记录.我们真正严格要求的唯一情况是消除二进制文件(例如,多次测试图像重新生成)和删除上游合并.

  • 不要让完美成为优秀的敌人,特别是对于文档或示例PR.如果您发现自己提出了许多小建议,可以针对原始分支打开一个PR,将更改推送到贡献者分支,或者合并PR,然后针对上游打开一个新的PR.

  • 如果您推送到贡献者分支,请留下评论解释您所做的事情,例如"我擅自将一个小清理PR推送到您的分支,感谢您的工作".如果您要对PR的代码或意图进行重大更改,请首先与贡献者确认.

分支和反向移植#

当前分支#

当前活跃的分支有

main

当前开发版本.未来的中版本 (v3.N.0) 或大版本 (v4.0.0) 将从此分支分出.

v3.N.x

Matplotlib 3.N 的维护分支.未来的小版本将从此分支标记.

v3.N.M-doc

当前小版本的文档.在小版本发布时,这将替换为新发布的正确命名的分支.

拉取请求的分支选择#

通常,所有拉取请求都应针对main分支.

其他分支通过 automatic 或 manual 提供.直接针对其他分支的情况很少,仅在特殊的维护工作时才需要.

反向移植策略#

对微版本分支 (v3.N.x) 的反向移植是将包含在下一个补丁(又名错误修复)版本中的更改.补丁版本的目的是修复错误,但不添加任何新的回归或行为更改.我们将始终尝试反向移植:

  • 关键错误修复(段错误,导入失败,用户无法解决的问题)

  • 修复在最近两个中版本中引入的回归

并且可能会尝试反向移植修复程序以解决旧版本中引入的回归.

如果反向移植不干净,例如,如果错误修复建立在我们不希望反向移植的其他代码更改之上,请权衡重新实现错误修复的努力和风险与错误的严重性.如有疑问,请避免反向移植.

当反向移植拉取请求失败或被拒绝时,将原始PR重新里程碑到下一个中版本,并留下评论解释原因.

唯一反向移植到文档分支 (v3.N.M-doc) 的更改是针对 doc 或 galleries 的更改.对 lib 或 src 的任何更改,包括仅 docstring 的更改,都不得反向移植到此分支.

自动反向移植#

我们使用 MeeseeksDev 机器人根据里程碑自动将合并反向移植到正确的维护分支.为了正常工作,必须在合并之前设置里程碑.如果您具有提交权限,也可以通过在 PR 上留言 @meeseeksdev backport to BRANCH 在合并后手动触发该机器人.如果存在冲突,MeeseeksDev 会通知您需要手动完成反向移植.

目标分支通过在里程碑描述中单独一行添加 on-merge: backport to TARGETBRANCH 进行配置.

如果机器人未按预期工作,请向 MeeseeksDev 报告问题.

手动反向移植#

进行反向移植时,请复制 MeeseeksDev 使用的表单, 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.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

自行决定是直接推送到 upstream 还是打开 PR; 务必推送到或 PR 到 v2.2.x upstream 分支,而不是 main !

On this page