拉取请求指南#

GitHub 上的拉取请求 (PRs) 是向 Matplotlib 的代码和文档贡献的机制。

我们重视来自各种经验水平的人的贡献。特别是，如果这是你的第一个PR，不一定要求完美。我们会指导你完成PR过程。尽管如此，请尽量遵循我们的指南，以帮助使PR过程快速顺利。如果你的拉取请求不完整或正在进行中，请在GitHub上将其标记为 草稿拉取请求 ，并指定开发者提供什么样的反馈会有帮助。

请对评审者保持耐心。我们尽力快速响应，但我们带宽有限。如果在几天内没有反馈，请通过在您的PR中发布评论或在 沟通渠道 上联系我们来提醒我们。

拉取请求作者摘要#

我们建议您在提交拉取请求之前，检查您的贡献是否符合以下指南：

  • 更改，包括新功能和错误修复，应有良好的测试覆盖率。更多详情请参见 测试。

  • 如有必要，更新 文档。

  • 所有公共方法都应有适当的、包含示例用法的说明文档。请使用 文档字符串标准。

  • 对于高级绘图函数，考虑在 示例画廊 中添加一个小示例。

  • 如果你添加了一个主要的新功能或以向后不兼容的方式更改了API，请按照 API 指南 中的描述进行文档化。

  • 代码应遵循我们在 编码指南 中记录的约定。

  • 在添加或更改公共函数签名时，添加 类型提示。

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

在Github上提交拉取请求时，请确保：

  • 更改是在 特性分支 上进行的。

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

  • 拉取请求的目标是 主分支

  • 如果你的拉取请求解决了某个问题，请使用标题来描述该问题（例如“添加绘制时间差的功能”），并在拉取请求描述中提及问题编号，以确保创建到原始问题的链接（例如“关闭 #8869”或“修复 #8869”）。这将确保在合并你的PR时，提到的原始问题会自动关闭。更多详情，请参阅 链接问题和拉取请求。

  • pr-自动化测试 通过

有关创建和管理拉取请求的指导，请参阅我们的 贡献指南 和 拉取请求工作流程 指南。

拉取请求审阅者摘要#

请帮忙审查并合并PR！

如果你有提交权限，那么你被信任去使用它们。请对贡献者保持耐心和 友善 。

在审查时，请确保在合并之前，拉取请求满足以下要求：

内容#

  • 这个功能 / 修复合理吗？

  • 该PR是否符合 编码指南 ？

  • 是否更新了 文档 （文档字符串、示例、新增内容、API 变更）？

  • 这个改动纯粹是风格上的吗？通常，如果不是作为其他非风格工作的部分，这样的改动是不被鼓励的，因为它模糊了代码功能改动的git历史。作为更大重构/重写的一部分，重新调整方法或文档字符串的格式是可以接受的。

工作流程#

详细指南#

文档#

  • 每个新功能都应该被记录。如果是新模块，别忘了在API文档中添加一个新的rst文件。

  • 每个高级绘图函数在文档字符串的 Examples 部分应有一个小示例。这应尽可能简单以展示方法。更复杂的示例应放入 examples 目录中的专用示例文件中，这些文件将在文档中的示例画廊中呈现。

  • 构建文档并确保所有格式警告都已处理。

  • 请参阅 编写文档 以获取我们的文档风格指南。

标签#

  • 如果你有权限设置标签，请用描述性的标签标记PR。查看 标签列表。

  • 如果PR对轮子构建Action进行了更改，请添加“Run cibuildwheel”标签以启用轮子测试。

里程碑#

根据以下指南设置里程碑：

  • 新功能和API变更 被里程碑标记为下一个中版本发布 v3.N.0。

  • Bug修复、发布代码的测试和文档字符串的更改 可能会被标记为下一个微版本 v3.N.M。

  • *文档更改*（仅限 .rst 文件和示例）可能会被标记为 v3.N-doc。

如果有多个规则适用，请选择上述列表中第一个匹配的规则。有关应该或不应该回溯的详细指导，请参阅 回溯策略。

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

所有拉取请求应针对主分支。里程碑标签会触发 自动回退 ，为具有相应分支的里程碑。

合并#

作为一个指导原则，我们要求在合并拉取请求之前，必须获得两名核心开发者（拥有提交权限的开发者）的 批准 。这种双人审查策略将确保项目方向的一致性并防止意外错误。如果变更不根本且可以随时在未来轻松回滚，则允许在获得一次批准的情况下合并。

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

  • 文档和示例 可以在单一批准下合并。使用“这是否比以前更好？”作为审查标准。

  • 小型的 基础设施更新，例如临时固定损坏的依赖项或对CI配置的小改动，可能只需一次批准即可合并。

  • *代码变更*（src 或 lib 中的任何内容）必须获得两项批准。

    确保所有API更改都记录在 doc/api/next_api_changes 子目录下的一个文件中，并且重要的新功能在 doc/user/whats_new 中有条目。

    • 如果一个PR已经得到了正面的评审，一个核心开发者（例如第一个评审者，但不一定是）可以为该PR争取合并。为此，他们应在GitHub和开发者邮件列表上通知所有核心开发者，并使用“Merge with single review?”标签标记该PR。其他核心开发者可以评审该PR并决定合并或拒绝，或者简单地要求在合并前进行第二次评审。如果在一周内没有人要求第二次评审，那么该PR可以基于那次单一评审进行合并。

      核心开发者一次应只支持一个PR，并且我们应尽量保持支持的PR流程合理。

在给出最后的必要批准后，批准的作者应合并PR。PR作者不应自行合并，除非另一位审查者明确允许（例如，“批准条件为CI通过，可在绿色状态下自行合并”，或“接受或忽略评论。你可以自行合并”）。

自动化测试#

在合并之前，PR 应该通过 自动化测试。如果你不确定为什么测试失败，可以在 PR 中或在我们的 沟通渠道 中询问。

提交次数与合并#

  • 压扁是逐案处理的。平衡点在于减轻贡献者的负担，保持相对干净的历史记录，以及保持历史记录可用于二分查找。我们唯一真正严格要求的是消除二进制文件（例如多次重新生成测试图像）和删除上游合并。

  • 不要让完美成为好的敌人，尤其是在文档或示例PR中。如果你发现自己提出了许多小建议，可以针对原始分支提交PR，推送到贡献者分支，或者合并PR后再针对上游提交新的PR。

  • 如果你推送到了贡献者的分支，请留下评论解释你做了什么，例如“我冒昧地推送了一个小的清理PR到你的分支，感谢你的工作。”。如果你打算对代码或PR的意图进行重大更改，请先与贡献者确认。

分支和回退#

当前分支#

当前活跃的分支是

主

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

v3.N.x

Matplotlib 3.N 的维护分支。未来的微版本将从这里标记。

v3.N.M-doc

当前微版本的文档。在微版本发布时，这将被新版本的正确命名的分支所替换。

拉取请求的分支选择#

通常，所有拉取请求都应针对主分支。

其他分支通过 自动 或 手动 进行处理。直接针对其他分支的操作仅在特殊维护工作中很少需要。

回溯策略#

对微版本分支（v3.N.x）的回溯是将在下一次补丁（又名错误修复）版本中包含的更改。补丁版本的目标是修复错误，而不添加任何新的回归或行为变化。我们将始终尝试进行回溯：

  • 关键错误修复（段错误、导入失败、用户无法解决的问题）

  • 修复了最近两个meso版本中引入的回归问题

并且可能会尝试回溯修复在旧版本中引入的回归问题。

在回退不干净的情况下，例如如果错误修复是基于我们不想回退的其他代码更改之上构建的，权衡重新实现错误修复的努力和风险与错误的严重性。如有疑问，倾向于不回退。

当回退一个拉取请求失败或被拒绝时，将原始PR重新里程碑到下一个中程发布，并留下评论解释原因。

回溯到文档分支（v3.N.M-doc）的唯一更改是针对 doc 或 galleries 的更改。任何针对 lib 或 src 的更改，包括仅文档字符串的更改，都不应回溯到此分支。

自动回溯#

我们使用 MeeseeksDev 机器人来自动将合并回溯到基于里程碑的正确维护分支。为了正常工作，必须在合并之前设置里程碑。如果你有提交权限，机器人也可以在合并后通过在 PR 上留言 @meeseeksdev 回溯到 BRANCH 来手动触发。如果有冲突，MeeseeksDev 会通知你需要手动进行回溯。

目标分支的配置是通过在其里程碑描述中单独一行放置 on-merge: backport to TARGETBRANCH 来实现的。

如果机器人没有按预期工作，请向 MeeseeksDev 报告问题。

手动回传#

在进行backports时，请复制MeeseeksDev使用的格式，Backport PR #XXXX: PR的标题。如果你需要手动解决冲突，请在提交信息中注明这些冲突以及你是如何解决它们的。

我们从主分支向 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

使用你的判断来直接推送到上游或打开一个PR；确保推送到或PR针对 v2.2.x 上游分支，而不是 main！

On this page