Bug 分类和问题管理#

问题跟踪器 在项目中的沟通中非常重要，因为它作为提出功能请求、报告错误、确定主要工作项目和讨论优先事项的集中地点。因此，精心管理问题列表非常重要，为问题添加标签并关闭已解决或无法解决的问题。

撰写定义明确的问题可以增加其成功解决的机会。关于如何撰写一个好的问题的指南可以在 这里 找到。本页的建议改编自 scikit learn 和 Pandas 的贡献指南。

改进问题报告#

分类问题不需要对 Matplotlib 的内部有特别的专业知识，但对项目极其有价值，我们欢迎任何人参与问题分类！然而，不属于 Matplotlib 组织的人没有 权限更改里程碑、添加标签或关闭问题。

如果你没有足够的GitHub权限做某些事情（例如添加标签、关闭问题），请留下评论并提出你的建议！

以下操作通常很有用：

  • 记录缺少重现问题所需元素的问题，例如代码示例

  • 建议更好地使用代码格式（例如，在Markdown中使用三重反引号）。

  • 建议重新表述标题和描述，使其更明确地说明要解决的问题

  • 在简要描述相关问题或讨论时，提及它们之间的关联，例如“另见 #xyz 以了解类似的尝试”或“另见 #xyz 其中报告了同样的问题”，可以提供上下文并有助于讨论。

  • 验证问题是否可重现

  • 将问题分类为功能请求、长期存在的错误或回归问题

维护者和分类团队成员#

除了上述内容，维护者和分类团队可以执行以下重要任务：

  • 更新问题和PR的标签：查看 可用的GitHub标签列表。

  • 分类问题：

    • 重现问题，如果发布的代码是一个错误，请用“status: confirmed bug”标记该问题。

    • 识别回归，确定报告的错误在Matplotlib的最近版本中是否按预期工作，如果是，则确定最后一个正常工作的版本。回归应标记为下一个错误修复版本的里程碑，并可能被标记为“发布关键”。

    • 关闭使用问题 并礼貌地引导报告者使用 discourse 或 Stack Overflow，并标记为“社区支持”。

    • 关闭重复问题，在确认它们确实是重复问题之后。理想情况下，原始提交者将讨论转移到较早的、重复的问题上。

    • 关闭无法复现的问题，在留出时间（至少一周）以添加额外信息之后

准备PR以供审查#

鼓励审查代码。贡献者和用户欢迎根据我们的 审查指南 参与审查过程。

分类工作流程#

以下工作流程是处理问题分类的一个好方法：

  1. 感谢报告者提出问题

    问题追踪器是许多人与 Matplotlib 项目本身首次互动的地方，而不仅仅是使用该库。因此，我们希望它是一个受欢迎、愉快的体验。

  2. 这是一个使用问题吗？如果是的话，请用礼貌的消息关闭它。

  3. 是否提供了必要的信息？

    检查发帖人是否填写了问题模板。如果缺少关键信息（Python 版本、使用的 Matplotlib 版本、操作系统及后端），请礼貌地要求原发帖人提供这些信息。

  4. 问题是最小的且可复现的吗？

    对于错误报告，我们要求报告者提供一个最小可复现的示例。请参阅 Matthew Rocklin 的 这篇有用的文章 以获得良好的解释。如果示例不可复现，或者显然不是最小的，请随意询问报告者是否可以提供一个示例或简化所提供的示例。请承认编写最小可复现的示例是艰巨的工作。如果报告者遇到困难，您可以尝试自己编写一个。

    如果提供了一个可复现的例子，但你看到了一个简化版本，请添加你更简单的可复现例子。

    如果你无法重现该问题，请报告你的操作系统、Python 和 Matplotlib 版本。

    如果我们需要从当前或上一步骤获取更多信息，请用“status: needs clarification”标记问题。

  5. 这是一个回归问题吗？

    虽然我们努力打造一个无缺陷的库，但回归问题是最优先考虑的。如果我们破坏了*曾经*正常工作的用户代码，我们应该在下一个微版本中修复它！

    尝试通过在旧版本的 Matplotlib 上运行重现代码来确定回归发生的时间。这可以通过 Matplotlib 的发布版本（以获取它最后正常工作的版本）或使用 git bisect 来找到首次出现问题的提交来完成。

  6. 这是一个重复的问题吗？

    我们有许多开放的问题。如果一个新问题似乎是重复的，请指向原始问题。如果是明显的重复，或者共识认为它是多余的，请关闭它。确保仍然感谢报告者，并鼓励他们在原始问题上发表意见，并尝试修复它。

    如果新问题提供了相关信息，例如更好或稍有不同的示例，请将其作为评论添加到原始问题中，或编辑原始帖子。

    用“status: duplicate”标签标记已关闭的问题

  7. 确保标题准确反映问题。如果你有必要的权限，如果标题不清楚，请自行编辑。

  8. 添加相关标签，例如当问题是关于文档时添加“文档”，如果是明显的错误则添加“错误”，如果是新功能请求则添加“新功能”，...

    如果问题定义明确且修复看起来相对简单，请将问题标记为“Good first issue”（并可能附上修复描述或提示，指出代码库中开始查找的位置）。

    一个额外的有用步骤可以是标记相应的模块，例如在相关时标记“GUI/Qt”标签。

分类团队#

如果你想加入分类团队：

  1. 正确地分类2-3个问题。

  2. 请在 Matplotlib 组织中（公开或私下）请求某人推荐你加入分类团队（在 GitHub 评论的右上角寻找“成员”）。如果你曾与某人一起处理过分类的问题，他们将是一个合适的人选。

  3. 负责任地行使你的新权力！

任何拥有提交或整理权限的人都可以通过向 matplotlib-steering-council@numfocus.org 发送电子邮件来提名用户加入整理团队。

On this page