问题分类

目前，Black 使用问题跟踪器来处理 bug、功能请求、建议的风格修改以及一般用户支持。每个问题都需要进行分类，以便最终能够以某种方式解决。本文档概述了分类过程，以及当前的指南和建议。

提示

如果你正在寻找一种无需提交补丁就能做出贡献的方式，这可能适合你。由于 Black 是一个热门项目，它的问题跟踪器非常繁忙，总是需要比现有资源更多的关注。虽然分类并不是最光彩照人或技术上最具挑战性的贡献形式，但它仍然很重要。例如，我们想知道那个旧的 bug 报告是否仍然可以重现！

你可以通过阅读本文档，然后回复问题来轻松入门。

如果你贡献足够多，并且待了足够长的时间，你甚至可能会获得分类权限！

基础

Black 收到大量不同的问题，从 bug 报告到用户支持问题。分类就是识别、组织并启动问题在其生命周期中通向解决的旅程。

更具体地说，分类问题意味着

  • 识别问题属于什么类型和类别

  • 确认 bug

  • 如果需要，询问问题/进一步信息

  • 链接相关问题

  • 提供最初的反馈/支持

请注意，分类通常是对问题的第一个回应，因此不要担心问题在最初分类后没有取得太大进展。分类的主要目标是为未来更具体的开发或讨论做好准备，以便最终能够解决问题。

bug 报告或用户支持问题的生命周期通常是这样的

  1. 问题正在等待分类

  2. 已识别 - 已用类型标签和其他相关标签标记，可能仍然需要更多细节或功能性重现（因此应该标记为 S: needs repro 或 S: awaiting response）

  3. 已确认 - 问题可以重现，并且已提供必要的信息

  4. 讨论 - 已完成最初的分类，现在正在讨论如何最好地解决问题的总体细节

  5. 等待修复 - 问题不再需要进一步讨论，解决 PR 是下一步

  6. 已关闭 - 问题已解决，原因包括

    • 问题无法重现

    • 问题已修复

    • 与其他现有问题重复或无效

对于增强、文档和风格问题，生命周期看起来非常相似，但细节不同

  1. 问题正在等待分类

  2. 已识别 - 已用类型标签和其他相关标签标记

  3. 讨论 - 目前正在讨论建议更改的优点，PR 可以接受，但被拒绝的风险很大

  4. 已接受并等待 PR - 已确定建议更改是可以的，并且欢迎 PR（S: accepted）

  5. 已关闭: - 问题已解决，原因包括

    • 建议的更改已实施

    • 它被拒绝了（由于技术问题、道德冲突等）

    • 与现有问题重复或无效

注意: 文档问题目前不使用 S: accepted 标签，因为它们不太可能被拒绝。

标签

我们使用标签来组织、跟踪进度并帮助有效地分配工作。

我们的标签分为几个组，由其前缀标识

  • T - 类型: 问题的/PR 的一般类型

  • C - 类别: 关注的领域，从 bug 类型到项目维护

  • F - 格式化区域: 与 C 相似，但专门针对格式化

  • S - 状态: 此问题当前处于解决的哪个阶段？

  • R - 解决方式: 问题/PR 如何/为何被解决？

我们还有一些独立的标签

  • good first issue: 对初学者友好的问题（将显示在 GitHub 横幅中，供首次访问存储库的访问者查看）

  • help wanted: 需要大量工作才能取得进展的复杂问题（也会显示在各种 GitHub 页面中）

  • skip news: 用于微不足道且不需要 CHANGELOG 条目的 PR（并跳过 CHANGELOG 条目检查）

注意

我们确实对 PR 使用标签，尤其是 skip news 标签，但我们并不严格要求这样做。只需根据你的判断，选择对特定 PR 有意义的标签（如果有的话）。

项目

为了实现更普遍和广泛的目标，我们使用项目来跟踪工作。有些可能是长期项目，没有真正结束（例如，“惊人的文档”项目），而另一些则可能更集中，并有明确的结束时间（例如“进入测试版”项目）。

注意

要修改 GitHub 项目，你需要拥有 写仓库权限级别或更高。

关闭问题

关闭问题表示问题已到达其生命周期的尽头，因此关闭问题应谨慎对待。以下是每种类型问题的常规建议。请注意，这些只是指南，如果你的判断认为应该采用其他方式，完全可以按照你的判断去做。

对于大多数问题，在解决 PR 后手动或自动关闭问题是理想的。对于 bug 报告，如果 bug 已经修复，请尝试在关闭之前与问题提交者确认他们的具体案例已解决。请注意，我们会在修复 main 分支中的问题后立即将其关闭。这并不一定意味着它们已经发布。

设计和增强问题也应该在清楚地知道提议的更改不会被实施时关闭，无论是在大量讨论后确定，还是简单地违反了 Black 的信条。如果此类问题变得激烈，如果问题足够严重，可以关闭并锁定（尽管最好与核心团队联系）。

用户支持问题最好由作者关闭，或者当问题明显以某种方式解决时。

重复和无效问题应该始终关闭，因为它们毫无用处，并且会给已经很繁忙的问题跟踪器增加噪音。不过，在将问题标记为重复并关闭之前，务必确保它确实是重复的，而不是仅仅非常相似。

常见报告

有些问题经常被打开，例如关于 Black 格式化的代码导致 E203 消息的问题。即使这些问题可能很大程度地重复，它们仍然需要分类，这会占用其他事情的宝贵时间（尽管它们通常会跳过大多数生命周期，因为它们在分类时被关闭）。

以下是一些最常见的问题，以及你可以使用的预制回复

“Black 没有删除尾随逗号！”

Black used to remove the trailing comma if the expression fits in a single line, but this was changed by #826 and #1288. Now a trailing comma tells Black to always explode the expression. This change was made mostly for the cases where you _know_ a collection or whatever will grow in the future. Having it always exploded as one element per line reduces diff noise when adding elements. Before the "magic trailing comma" feature, you couldn't anticipate a collection's growth reliably since collections that fitted in one line were ruthlessly collapsed regardless of your intentions. One of Black's goals is reducing diff noise, so this was a good pragmatic change.

So no, this is not a bug, but an intended feature. Anyway, [here's the documentation](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#the-magic-trailing-comma) on the "magic trailing comma", including the ability to skip this functionality with the `--skip-magic-trailing-comma` option. Hopefully that helps solve the possible confusion.

“Black 格式化的代码违反了 Flake8 的 E203！”

Hi,

This is expected behaviour, please see the documentation regarding this case (emphasis
mine):

> PEP 8 recommends to treat : in slices as a binary operator with the lowest priority, and to leave an equal amount of space on either side, **except if a parameter is omitted (e.g. ham[1 + 1 :])**. It recommends no spaces around : operators for “simple expressions” (ham[lower:upper]), and **extra space for “complex expressions” (ham[lower : upper + offset])**. **Black treats anything more than variable names as “complex” (ham[lower : upper + 1]).** It also states that for extended slices, both : operators have to have the same amount of spacing, except if a parameter is omitted (ham[1 + 1 ::]). Black enforces these rules consistently.

> This behaviour may raise E203 whitespace before ':' warnings in style guide enforcement tools like Flake8. **Since E203 is not PEP 8 compliant, you should tell Flake8 to ignore these warnings**.

https://black.pythonlang.cn/en/stable/the_black_code_style/current_style.html#slices

Have a good day!