Bug 分类和问题管理#

问题跟踪器对项目内的沟通至关重要:它帮助开发者识别需要处理的重大项目,并讨论优先级。因此,对其进行管理、为问题添加标签以及关闭不必要的问题非常重要。

处理问题以改进它们#

改进问题会增加其成功解决的机会。提交好问题的指南可以在此处找到。第三方可以提供有用的反馈,甚至对问题添加评论。以下行动通常很有用

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

  • 建议更好地使用代码格式

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

  • 链接到相关问题或讨论,并简要说明它们之间的关系,例如“另请参阅 #xyz,这是一次类似的尝试”或“另请参阅 #xyz,其中 SomeEstimator 中发生了同样的事情”,这提供了上下文并有助于讨论。

处理 PR 以协助审查#

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

核心团队和贡献者体验团队成员的分类操作#

除了上述内容,核心团队和贡献者体验团队的成员还可以执行以下重要任务

  • 更新问题和 PR 的标签:参见可用 GitHub 标签列表。

  • 确定 PR 是否必须重新标记为停滞或需要帮助(这在冲刺期间通常非常重要,因为存在创建许多未完成 PR 的风险)

  • 如果一个停滞的 PR 被一个新的 PR 接管,则将该停滞的 PR 标记为“已取代”(Superseded),在该停滞的 PR 上留下评论并链接到新的 PR,并很可能关闭该停滞的 PR。

  • 分类问题

    • 关闭使用问题,并礼貌地建议报告者改用 Stack Overflow。

    • 关闭重复问题,在检查它们确实是重复后。理想情况下,原始提交者将讨论转移到更旧的重复问题中

    • 关闭无法重现的问题,在留出时间(至少一周)添加额外信息后

预设回复在分类时非常有用,可以节省时间,同时保持热情和礼貌。

有关组织中的角色,请参阅 GitHub 描述。

问题分类的典型工作流程#

以下工作流程[1]是处理问题分类的好方法

  1. 感谢报告者提出问题

    问题跟踪器是许多人与 scikit-learn 项目本身(不仅仅是使用库)的第一次互动。因此,我们希望它是一个热情、愉快的体验。

  2. 这是一个使用问题吗?如果是,请用礼貌的信息关闭它(这里有一个例子)。

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

    如果缺少关键信息(如使用的 scikit-learn 版本),请随时要求提供,并将问题标记为“需要信息”(Needs info)。

  4. 这是一个重复问题吗?

    我们有许多开放的问题。如果新问题似乎是重复的,请指向原始问题。如果它是一个明显的重复,或者一致认为它是冗余的,请关闭它。请务必感谢报告者,并鼓励他们在原始问题中发表意见,并尝试解决它。

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

  5. 确保标题准确反映问题。如果标题不清楚,在您有必要权限的情况下自行编辑。

  6. 问题是否最小且可重现?

    对于 bug 报告,我们要求报告者提供一个最小可重现的示例。请参阅 Matthew Rocklin 的这篇有用文章,以获取很好的解释。如果示例不可重现,或者明显不最小,请随时询问报告者是否可以提供示例或简化提供的示例。请承认编写最小可重现示例是项艰苦的工作。如果报告者遇到困难,您可以尝试自己编写一个。

    如果提供了可重现的示例,但您发现可以简化,请添加您更简单的可重现示例。

  7. 添加相关标签,例如当问题与文档相关时添加“文档”(Documentation),如果明显是 bug 则添加“Bug”,如果是增强请求则添加“增强”(Enhancement),等等。

    如果问题明确定义,且修复看起来相对简单,则将问题标记为“初学者友好”(Good first issue)。

    一个额外的有用步骤是标记相应的模块,例如在相关时标记 sklearn.linear_models

  8. 如果存在“需要分类”(Needs Triage)标签,请将其从问题中移除。