缺陷分类和问题管理#
issue tracker 对于项目中的沟通非常重要,因为它充当了集中位置,用于提出功能请求,报告错误,确定要处理的主要项目以及讨论优先级.因此,管理问题列表,向问题添加标签以及关闭已解决或无法解决的问题非常重要.
编写定义明确的问题会增加其成功解决的机会.有关编写好的问题的指南可以在 here 中找到.本页中的建议改编自 scikit learn 和 Pandas 贡献指南.
改进问题报告#
Triaging issues does not require any particular expertise in the internals of Matplotlib, is extremely valuable to the project, and we welcome anyone to participate in issue triage! However, people who are not part of the Matplotlib organization do not have permissions to change milestones, add labels, or close issue.
如果您没有足够的 GitHub 权限来执行某些操作(例如,添加标签,关闭问题),请留下包含您的建议的评论!
以下操作通常很有用:
记录缺少重现问题要素的问题,例如代码示例
建议更好地使用代码格式(例如,markdown 中的三个反引号).
建议重新措辞标题和描述,使其更明确要解决的问题
链接到相关问题或讨论,同时简要描述它们的关联方式,例如"另请参见 #xyz 以了解对此的类似尝试"或"另请参见 #xyz,其中报告了相同的事情"提供上下文并有助于讨论
验证问题是否可重现
将问题分类为功能请求,长期存在的错误或回归
维护人员和分类团队成员#
除了上述内容外,维护人员和分类团队还可以执行以下重要任务:
Update labels for issues and PRs: see the list of available GitHub labels.
分类问题:
重现该问题,如果发布的代码是一个错误,则使用"status: confirmed bug"标记该问题.
识别回归,确定报告的错误是否曾经在最近的 Matplotlib 版本中按预期工作,如果是,则确定最后一个正常工作的版本.回归应针对下一个错误修复版本进行里程碑标记,并且可以标记为"Release critical".
close usage questions and politely point the reporter to use discourse or Stack Overflow instead and label as "community support".
在检查它们确实是重复的之后,关闭重复的问题. 理想情况下,原始提交者会将讨论移到较旧的重复问题中
在留出时间(至少一周)添加额外信息后,关闭无法复制的问题
准备PR以供审查#
同样鼓励代码审查.欢迎贡献者和用户按照我们的 review guidelines 参与审查过程.
问题分流工作流程#
以下工作流程是处理问题分流的好方法:
感谢报告者提出问题
问题跟踪器是许多人与 Matplotlib 项目本身的第一次交互,而不仅仅是使用库.因此,我们希望它成为一种受欢迎的,令人愉快的体验.
这是一个用法问题吗?如果是,请用礼貌的信息关闭它.
是否提供了必要信息?
检查发布者是否填写了问题模板.如果缺少关键信息(Python 版本,Matplotlib 版本,操作系统和后端),请礼貌地要求原始发布者提供信息.
这个问题是否精简且可重现?
对于错误报告,我们要求报告者提供一个最小的可重现示例.有关很好的解释,请参阅 Matthew Rocklin 的 this useful post .如果示例不可重现,或者如果明显不是最小的,请随时询问报告者是否可以提供一个示例或简化提供的示例.请承认编写最小的可重现示例是艰苦的工作.如果报告者正在努力,您可以尝试自己编写一个.
如果提供了可重现的示例,但您看到了简化,请添加您更简单的可重现示例.
如果您无法重现该问题,请报告您的操作系统,Python 和 Matplotlib 版本.
如果我们需要来自此步骤或上一步的更多信息,请使用"status: needs clarification"标记该问题.
这是一个回归问题吗?
虽然我们致力于创建一个没有错误的库,但回归问题具有最高的优先级.如果我们破坏了以前可以工作的用户代码,我们应该在下一个微版本中修复它!
尝试通过针对旧版本的 Matplotlib 运行重现代码来确定回归发生的时间.这可以通过 Matplotlib 的发布版本(以获取它最后一次工作的版本)或使用 git bisect 来查找第一个被破坏的提交来完成.
这是一个重复的问题吗?
我们有很多未解决的问题.如果新问题似乎是重复的,请指向原始问题.如果它是一个明显的重复,或者一致认为是多余的,请关闭它.确保仍然感谢报告者,并鼓励他们在原始问题中提出意见,并尝试修复它.
如果新问题提供了相关信息,例如更好或略有不同的示例,请将其作为评论或编辑添加到原始问题的原始帖子中.
使用"status: duplicate"标记关闭的问题
确保标题准确反映了问题.如果标题不清楚,如果您有必要的权限,请自行编辑.
添加相关的标签,例如,当问题是关于文档时,添加"Documentation",如果它显然是一个错误,则添加"Bug",如果它是一个新的功能请求,则添加"New feature",...
如果问题定义明确,并且修复看起来相对简单,请将该问题标记为"Good first issue"(并且可能需要描述修复方法,或者提示在代码库中的哪个位置开始查找).
一个额外的有用步骤是标记相应的模块,例如,在相关时标记"GUI/Qt"标签.
问题分流团队#
如果您想加入问题分流团队:
正确分流 2-3 个问题.
请 Matplotlib 组织中的某人(公开或私下)推荐您加入问题分流团队(在 GitHub 上的评论的右上角查找"Member").如果您与某人合作进行了问题分流,那么他们将是一个不错的选择.
负责任地行使你的新权力!
任何拥有提交或分流权限的人都可以通过发送电子邮件至 matplotlib-steering-council@numfocus.org 来提名用户加入分流团队.