贡献指南#
你发现了一个Matplotlib中的错误或其他想要改变的东西——太棒了!
你已经找到了解决方法——甚至更好!
你想告诉我们这件事——最好不过了!
下面,你可以找到多种贡献方式,以及如何与 Matplotlib 社区联系。
开始#
对于新贡献者没有预定义的路径——我们建议查看现有的问题和拉取请求讨论,并在拉取请求审查期间关注对话以获取上下文。或者你可以深入研究代码库的一个子集,以了解正在发生的事情。
我真的有什么可以贡献给 Matplotlib 的吗?
100% 是的!有许多方式可以为我们的社区做出贡献。请查看以下部分以了解更多信息。
以下是几种典型的新贡献者类型:
你是一个 Matplotlib 用户,你发现了一个 bug,一个潜在的改进,或者一些让你烦恼的事情,而你可以修复它。
你可以在我们的问题跟踪器中搜索一个描述你问题的现有问题,或者打开一个新问题来通知我们你观察到的问题,并讨论解决它的最佳方法。如果你的贡献不会在GitHub上被记录(社交媒体、沟通、教育内容),你也可以在gitter、Discourse <https://discourse.matplotlib.org/>`__上联系我们,或者参加我们的任何`社区会议。
你不是一个普通的 Matplotlib 用户,而是一个领域专家:你对可视化、3D 绘图、设计、技术写作、统计学或其他 Matplotlib 可以改进的领域有所了解。
太棒了 -- 你有一个特定的应用和领域焦点,可以从那里开始。在这种情况下,维护者可以帮助你找出最佳的实现方式;打开一个议题或拉取请求,提供一个起点,我们会很乐意讨论技术方法。
如果你愿意,你可以使用 GitHub 的“草稿”拉取请求功能 ,并在你正在进行的任何工作上请求早期反馈,但你应该知道,维护者可能不会审查你的贡献,除非它在 GitHub 上处于“准备审查”状态。
你是 Matplotlib 的新手,无论是作为用户还是贡献者,你都希望开始贡献,但尚未发展出特定的兴趣。
在开源贡献时,拥有与该库的先前经验或关系会非常有帮助。这有助于你理解为什么事情是这样的,以及它们 应该 如何。第一手的经验和背景对于你能为讨论带来的内容(考虑到 Matplotlib 的广泛使用,在任何给定的讨论中,它很可能是一个独特的背景)以及更容易理解他人的立场都非常有价值。
理解整个代码库是一个长期项目,没有人期望你立即做到这一点。如果你决心开始使用 Matplotlib 并希望学习,通过基本功能,选择一个重点(3D、测试、文档、动画等),并通过阅读涉及这些主题的问题和拉取请求来获得该领域的背景知识,这是一个合理的方法。
代码#
您想要实现一个功能、修复一个错误或帮助维护 - 非常感谢!我们的库源代码可以在以下位置找到:
Python 库代码:
lib/
C扩展代码:
src/
测试:
lib/matplotlib/tests/
因为许多人使用和参与 Matplotlib 的开发,我们有一些指导原则来保持代码的一致性并减轻更改的影响。
代码通过拉取请求贡献,因此我们建议您从 如何提交拉取请求 开始。如果您遇到困难,请在 贡献者孵化器 上联系我们。
文档#
作为 Matplotlib 的终端用户,您可以做出有价值的贡献,因为您比核心开发者更清楚改进的潜力。例如,您可以:
我们的代码在 matplotlib/lib
的源代码文件中内联文档化。我们的网站结构反映了我们的文件夹结构,这意味着叙述文档的URL大致对应于其在文件夹结构中的位置:
使用库
galleries/plot_types/
users/getting_started/
galleries/user_explain/
画廊/教程/
galleries/examples/
doc/api/
关于这个库的信息
doc/install/
doc/project/
doc/devel/
doc/users/resources/index.rst
doc/users/faq.rst
其他文档是从以下外部资源生成的:
matplotlib.org 主页: matplotlib/mpl-brochure-site
贡献文档的说明和指南可以在以下找到:
文档
风格指南
标签指南
文档通过拉取请求贡献,因此我们建议您从 如何提交拉取请求 开始。如果这感觉有些吓人,我们鼓励您 提交一个问题 描述您想做的改进。如果您遇到困难,请在 贡献者孵化器 中寻求帮助。
分类#
我们感谢您帮助保持 问题追踪器 的组织性,因为这是我们集中处理功能请求、错误报告、跟踪主要项目和讨论优先级的地方。我们所说的分类的一些例子包括:
标记问题和拉取请求
验证错误报告
调试和解决问题
链接到相关问题、讨论和外部工作
我们的分类流程在 Bug 分类和问题管理 中有详细讨论。
如果您对流程有任何疑问,请在 贡献者孵化器 上联系。
社区#
Matplotlib 的社区由其成员构建,如果您想提供帮助,请参阅我们的 社区管理指南。
如果你能帮忙宣传,我们将不胜感激:在你的博客和文章中引用该项目,或者从你的网站链接到它!
如果 Matplotlib 对一个项目有所贡献,并因此导致科学出版物的产生,请根据 引用 Matplotlib 指南引用我们。
如果你开发了一个 Matplotlib 的扩展,请考虑将其添加到我们的 第三方包 列表中。
建立连接#
如果有疑问,我们建议一起行动!加入我们的活跃贡献者社区,其中许多人刚开始时也像你一样,他们很高兴欢迎你并支持你,帮助你了解我们的工作方式和资源所在。
贡献者孵化器#
孵化器是我们为新贡献者提供的非公开交流渠道。这是一个由核心 Matplotlib 开发者管理的私人 gitter_(聊天)房间,你可以在那里获得指导和支持,完成你的前几个 PR。这是一个你可以询问任何问题的地方:如何使用 git、GitHub,我们的 PR 审查流程是如何运作的,关于代码的技术问题,什么构成了好的文档或博客文章,如何参与社区工作,或者在提交 PR 前获得“预审查”。
要加入,请访问我们的公共社区_频道,并请求加入 #incubator
。我们的核心开发者之一会看到您的消息,并将您添加进去。
新贡献者会议#
我们每月举办一次会议,讨论新贡献者感兴趣的话题。任何人都可以参加、发言,或者只是坐下来聆听。我们的与会者包括其他新贡献者,以及维护者和资深贡献者,他们都热衷于支持新人的加入并分享他们的经验。你可以在 Scientific Python 网站 找到我们的社区日历链接,并且可以在 GitHub 上浏览之前的会议记录。我们建议加入会议以澄清任何疑问或未解决的问题,并认识一些在 GitHub 背后的真实人物 😉。你可以在 gitter 上联系我们以获取任何澄清或建议。我们 ❤ 反馈!
处理一个问题#
一般来说,Matplotlib 项目不分配问题。问题通过打开一个 PR 来“分配”或“认领”;没有其他分配机制。如果你已经打开了这样的 PR,请在问题线程中评论以避免工作重复。请检查是否有针对你正在处理的问题的现有 PR。如果有,尝试通过提交代码审查或评论 PR 来与作者合作,而不是打开一个新的 PR;重复的 PR 可能会被关闭。然而,如果现有的 PR 只是一个大纲,不太可能工作,或停滞不前,并且原作者没有回应,欢迎你参考旧的 PR 打开一个新的 PR。
好的第一个问题#
虽然欢迎任何贡献,但我们已将一些问题标记为特别适合新贡献者,标签为 good first issue。这些问题文档齐全,不需要对 Matplotlib 的内部有深入理解。这些问题可能还会附加一个难度标签。Difficulty: Easy
适合有较少 Python 经验的人。Difficulty: Medium
和 Difficulty: Hard
需要更多的编程经验。这可能是由于多种原因,尽管不一定同时具备所有这些原因:
问题出现在代码库中相互依赖性更强或存在遗留代码的区域。
它的任务定义不那么明确,这需要一些独立探索、提出建议或跟进讨论,以明确解决问题的良好路径。
它涉及 Python 特性,如装饰器和上下文管理器,由于我们的实现决策,这些特性具有细微差别。
开始一个拉取请求#
为 Matplotlib 贡献的首选方式是在 GitHub 上 fork 主仓库,然后提交一个“拉取请求”(PR)。你可以通过将 Matplotlib 仓库的副本克隆到你自己的计算机上,或者使用 GitHub Codespaces 来完成此操作,这是一个基于云的浏览器内开发环境,自带适当的设置以贡献于 Matplotlib。
工作流程概述#
工作流程的简要概述如下。
创建一个账户 如果你还没有GitHub账户的话。
通过点击页面顶部的 Fork 按钮来 Fork 项目仓库。这将在 GitHub 服务器上你的账户下创建代码的副本。
设置开发环境:
将此副本克隆到您的本地磁盘:
git clone https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git
查看 Matplotlib 仓库并激活你的开发环境:
通过点击GitHub网页界面上的绿色“Code”按钮并选择“Codespaces”标签,可以在你的分支上打开代码空间。
接下来,点击“在 <你的分支名称> 上打开代码空间”。你稍后可以更改分支,因此你可以选择默认的
main
分支。代码空间创建后,您将被带到一个新的浏览器标签页,您可以在那里使用终端激活一个名为
mpl-dev
的预定义 conda 环境:conda activate mpl-dev
使用以下命令安装本地版本的 Matplotlib:
python -m pip install --no-build-isolation --editable .[dev]
详情请参见 设置 Matplotlib 进行开发。
创建一个分支来保存你的更改:
git checkout -b my-feature origin/main
并开始进行更改。永远不要在
main
分支上工作!使用 Git 进行版本控制来完成此任务。Codespaces 会持续一段时间(查看 文档了解详情),并且可以在 codespaces 上进行管理。当你完成编辑例如
lib/matplotlib/collections.py
时,执行:git add lib/matplotlib/collections.py git commit
要在 Git 中记录你的更改,然后将它们推送到你的 GitHub 分支,请使用:
git push -u origin my-feature
GitHub Codespaces 工作流程#
如果你需要在Codespaces上使用Matplotlib输出打开一个GUI窗口,我们的配置包括一个基于 轻量级Fluxbox桌面 。你可以通过你的网络浏览器连接到这个桌面来使用它。要做到这一点:
- 按下
F1
或Ctrl/Cmd+Shift+P
并选择 Ports: 聚焦端口视图
在 VSCode 会话中将其聚焦。打开工具中的端口视图,选择noVNC
端口,然后点击地球图标。
- 按下
- 在出现的浏览器中,点击“连接”按钮并进入桌面
密码(默认为
vscode
)。
有关连接到桌面的更多详细信息,请查看 GitHub 说明。
查看文档#
如果你也构建了文档页面,你可以使用 Codespaces 查看它们。使用活动栏中的“扩展”图标来安装“Live Server”扩展。在资源管理器中找到 doc/build/html
文件夹,右键点击你想要打开的文件并选择“使用 Live Server 打开”。
在 Matplotlib 上发起一个拉取请求#
最后,访问 你的 fork 的 Matplotlib 仓库的网页,点击 比较并发起拉取请求 将你的更改发送给维护者进行审核。基础仓库是 matplotlib/matplotlib
,基础分支通常是 main
。更多指导,请参阅 GitHub 的 拉取请求教程。
有关如何为开发设置 Matplotlib 以及贡献最佳实践的更详细说明,请参阅 设置 Matplotlib 进行开发 和 开发工作流程。