贡献指南#

您发现了一个错误或 Matplotlib 中您想更改的其他内容--太棒了!

您已经找到了一种修复它的方法--那就更好了!

你想告诉我们这件事--最棒的是!

在下面,您可以找到多种贡献方式,以及如何与 Matplotlib 社区建立联系.

贡献方式#

我真的有东西可以贡献给 Matplotlib 吗?

100% 是的!有很多方法可以为我们的社区做出贡献.请查看以下各节以了解更多信息.

有几个典型的新贡献者简介:

  • 您是 Matplotlib 用户,您发现了一个错误,一个潜在的改进或一些让您恼火的东西,您可以修复它.

    您可以搜索我们的 issue 跟踪器,查找描述您的问题的现有 issue,或者打开一个新的 issue,告知我们您观察到的问题,并讨论修复它的最佳方法.如果您的贡献不会在 GitHub 上捕获(社交媒体,沟通,教育内容),您也可以在 gitter, Discourse 上与我们联系或参加我们的任何 community meetings .

  • 您不是 Matplotlib 的常规用户,但您是领域专家:您了解可视化,3D 绘图,设计,技术写作,统计或 Matplotlib 可以改进的其他领域.

    太棒了--你要专注于特定的应用和领域,可以从那里开始.在这种情况下,维护人员可以帮助您找出最佳的实施方案;打开一个 issue 或一个 pull request 并提供一个起点,我们将很乐意讨论技术方法.

    如果您愿意,您可以使用 GitHub functionality for "draft" pull requests 并请求您正在处理的任何内容的早期反馈,但您应该知道,维护人员可能不会审查您的贡献,除非它在 GitHub 上具有"准备好审查"状态.

  • 您是 Matplotlib 的新手,既是用户也是贡献者,并且想要开始贡献,但尚未培养出特定的兴趣.

    在进行开源贡献时,拥有一些先前的经验或与库的关系会非常有帮助.它可以帮助您了解事物的现状以及它们应该如何发展.拥有第一手经验和背景知识非常有价值,既可以为您带来对话的内容(并且鉴于 Matplotlib 的广泛使用,很可能在任何给定的对话中都是独特的背景),也可以更容易理解其他人的立场.

    理解整个代码库是一个长期的项目,没有人期望您立即完成.如果您决心开始使用 Matplotlib 并想学习,那么浏览基本功能,选择一个重点(3d,测试,文档,动画等),并通过阅读涉及这些主题的问题和拉取请求来了解该领域的背景知识,这是一个合理的方法.

代码#

您想要实现一个功能,修复一个 bug 或帮助维护 - 非常感谢!我们的库源代码可以在以下位置找到:

  • Python 库代码 lib/

  • C-扩展 代码 src/

  • 测试 lib/matplotlib/tests/

由于许多人使用和开发 Matplotlib,因此我们制定了指南来保持代码的一致性并减轻更改的影响.

代码通过拉取请求贡献,因此我们建议您从 启动一个pull request 开始.如果您遇到困难,请在 贡献者孵化器 上寻求帮助

文档#

作为 Matplotlib 的最终用户,您可以做出有价值的贡献,因为与核心开发人员相比,您可以更清楚地看到改进的潜力.例如,您可以:

  • 修复拼写错误

  • 澄清文档字符串

  • 编写或更新 example plot

  • 编写或更新全面的 tutorial

我们的代码以内联方式记录在 matplotlib/lib 的源代码文件中.我们的网站结构反映了我们的文件夹结构,这意味着叙述性文档的 URL 大致对应于它在我们文件夹结构中的位置:

使用库

  • galleries/plot_types/

  • users/getting_started/

  • galleries/user_explain/

  • galleries/tutorials/

  • galleries/examples/

  • doc/api/

关于库的信息

  • doc/install/

  • doc/project/

  • doc/devel/

  • doc/users/resources/index.rst

  • doc/users/faq.rst

其他文档是从以下外部来源生成的:

贡献文档的说明和指南可以在以下位置找到:

文档通过拉取请求贡献,因此我们建议您从 启动一个pull request 开始.如果这让您感到害怕,我们鼓励您 open an issue ,描述您将进行的改进.如果您遇到困难,请在 贡献者孵化器 上寻求帮助

分类#

我们感谢您帮助组织 issue tracker ,因为它是我们集中处理功能请求,错误报告,跟踪重大项目和讨论优先事项的位置.以下是我们所说的分类的一些示例:

  • 标记 issue 和拉取请求

  • 验证错误报告

  • 调试和解决问题

  • 链接到相关问题,讨论和外部工作

我们的分类过程在 缺陷分类和问题管理 中详细讨论.

如果您对该过程有任何疑问,请在 贡献者孵化器 上寻求帮助

社区#

Matplotlib 的社区由其成员构建,如果您想提供帮助,请参阅我们的 社区管理指南 .

如果您传播该项目,例如从您的博客和文章中引用该项目或从您的网站链接到该项目,这对我们有帮助!

如果 Matplotlib 对某个科学出版物相关的项目做出了贡献,请按照 引用 Matplotlib 指南引用我们.

如果您开发了 Matplotlib 的扩展,请考虑将其添加到我们的 third party package 列表中.

生成式人工智能使用限制#

我们期望社区成员进行真实的互动.请谨慎发布来自大型语言模型或类似生成式人工智能的输出作为 GitHub 或我们的 Discourse 服务器上的评论,因为这些评论往往是公式化的且内容含量较低.如果您使用生成式人工智能工具来辅助开发代码或文档更改,请确保您完全理解所提出的更改,并且能够解释为什么它们是正确的方法,以及对当前状态的改进.

新的贡献者#

对于新的贡献者,没有预定义的途径.我们建议查看现有的 issue 和 pull request 讨论,并在 pull request 审查期间关注对话,以获取上下文.或者您可以深入研究代码库的子集,以了解正在发生的事情.

新的贡献者会议#

我们每月举办一次会议,讨论新的贡献者感兴趣的主题. 任何人都可以参加,展示或旁听电话会议. 我们的与会者包括其他新贡献者,以及维护者和资深贡献者,他们热衷于支持新手的入职培训并分享他们的经验. 您可以在 Scientific Python website 上找到我们的社区日历链接,并且可以在 GitHub 上浏览之前的会议记录. 我们建议您参加会议以澄清任何疑问或挥之不去的问题,并了解 GitHub handles 背后的几个人 😉. 您可以通过 gitter 联系我们以获得任何澄清或建议. 我们 ❤ 反馈!

贡献者孵化器#

孵化器是我们非公开的,为新贡献者准备的交流渠道. 它是由核心 Matplotlib 开发人员主持的私有 gitter (聊天) 房间,您可以在其中获得最初几个 PR 的指导和支持. 您可以在这里提出任何问题:如何使用 git,GitHub,我们的 PR 审查流程如何运作,有关代码的技术问题,什么是好的文档或博客文章,如何参与社区工作,或者获得 PR 的"预审".

要加入,请转到我们的公共 community 频道,并要求将您添加到 #incubator . 我们的核心开发人员之一将看到您的消息并将您添加进去.

好的新手问题#

虽然欢迎任何贡献,但我们已将一些问题标记为特别适合新贡献者,使用了 good first issue 标签. 这些是有据可查的问题,不需要深入了解 Matplotlib 的内部结构. 这些问题可能还会标有难度. Difficulty: Easy 适合几乎没有 Python 经验的人. Difficulty: Medium 和 Difficulty: Hard 需要更多的编程经验. 这可能是由于多种原因造成的,其中包括但不一定同时包括:

  • 该问题存在于代码库中具有更多相互依赖性或遗留代码的区域中.

  • 它具有不太明确的任务,需要一些独立的探索,提出建议或后续讨论以阐明解决该问题的好方法.

  • 它涉及 Python 功能,例如装饰器和上下文管理器,由于我们的实现决策而具有细微之处.

首次贡献#

如果这是您的第一个开源贡献,或者您第一次为 Matplotlib 做贡献,并且您需要帮助或指导来找到一个好的首发问题,请不要再犹豫了.本节将指导您完成每个步骤:

  1. 导航到 issues page .

  2. 使用 "Difficulty: Easy" & "Good first Issue" 过滤标签(可选).

  3. 点击您想要处理的问题,并检查该问题是否已有待解决的pull request.

    • 判断您选择的问题是否合适的标准是问自己:"我是否可以在1-2周内独立提交一个PR?"

  4. 检查现有的pull requests(例如 PR #28476 )并通过问题编号进行过滤,以确保该问题未在进行中:

    • 如果问题已经有一个pull request(正在进行中),请标记正在处理该问题的用户,并要求合作(可选).

    • 如果不存在pull request,则创建一个 draft pull request 并遵循 pull request guidelines .

  5. 请熟悉pull request模板(见下文),并确保您理解/能够填写该模板,然后再打开您的pull request. 更多信息可以在 pull request guidelines 中找到.

Pull request template
<!--
Thank you so much for your PR!  To help us review your contribution, please check
out the development guide https://matplotlib.org/devdocs/devel/index.html
-->

## PR summary
<!-- Please describe the pull request, using the questions below as guidance, and link to any relevant issues and PRs:

- Why is this change necessary?
- What problem does it solve?
- What is the reasoning for this implementation?

Additionally, please summarize the changes in the title, for example "Raise ValueError on
non-numeric input to set_xlim" and avoid non-descriptive titles such as "Addresses
issue #8576".

If possible, please provide a minimum self-contained example.  If you have used
generative AI as an aid in preparing this PR, see
https://dev.matplotlib.org/devel/contributing.html#generative_ai.

-->


## PR checklist
<!-- Please mark any checkboxes that do not apply to this PR as [N/A].-->

- [ ] "closes #0000" is in the body of the PR description to [link the related issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)
- [ ] new and changed code is [tested](https://matplotlib.org/devdocs/devel/testing.html)
- [ ] *Plotting related* features are demonstrated in an [example](https://matplotlib.org/devdocs/devel/document.html#write-examples-and-tutorials)
- [ ] *New Features* and *API Changes* are noted with a [directive and release note](https://matplotlib.org/devdocs/devel/api_changes.html#announce-changes-deprecations-and-new-features)
- [ ] Documentation complies with [general](https://matplotlib.org/devdocs/devel/document.html#write-rest-pages) and [docstring](https://matplotlib.org/devdocs/devel/document.html#write-docstrings) guidelines

<!--We understand that PRs can sometimes be overwhelming, especially as the
reviews start coming in.  Please let us know if the reviews are unclear or
the recommended next step seems overly demanding, if you would like help in
addressing a reviewer's comments, or if you have been waiting too long to hear
back on your PR.-->

建立连接#

如有疑问,我们建议大家一起努力! 与我们活跃的贡献者社区建立联系,他们中的许多人在刚开始时也和您一样,并乐于欢迎您并支持您了解我们的工作方式以及事情的进展.您可以通过任何我们的 官方沟通渠道 联系我们. 对于开发问题,我们建议在我们的 development gitter 聊天室中联系,对于社区问题,请在 community 联系.

选择一个问题#

通常,Matplotlib项目不分配问题. 问题通过打开PR来"分配"或"声明"; 没有其他分配机制. 如果您已打开这样的PR,请在问题线程上发表评论,以避免重复工作. 请检查您要处理的问题是否存在现有的PR. 如果有,请尝试通过提交代码审查或在PR上发表评论来与作者合作,而不是打开新的PR; 重复的PR可能会被关闭. 但是,如果现有的PR是一个大纲,不太可能工作或停滞不前,并且原始作者没有回应,请随时打开一个新的PR,并引用旧的PR.

启动一个pull request#

贡献Matplotlib的首选方式是fork GitHub上的 main repository ,然后提交"pull request"(PR). 要处理一个pull request:

  1. 首先,按照 设置Matplotlib进行开发 中的说明,通过将Matplotlib存储库的副本克隆到您自己的计算机或使用Github codespaces来设置开发环境

  2. 然后按照 development workflow 中的指导启动一个pull request

  3. 启动后,检查您的贡献是否符合 pull request guidelines ,并根据需要 update the pull request .

  4. 最后,如果在等待反馈的时间超过几天,请与PR上的维护者联系.

如果您有任何疑问,请在 贡献者孵化器 上联系,并加入 新的贡献者会议 .

On this page