Issue トリアージ

現在、Blackでは、バグ、機能リクエスト、スタイル変更の提案、一般的なユーザーサポートのために、issue トラッカーを使用しています。これらのissueはそれぞれトリアージされ、最終的に何らかの形で解決される必要があります。このドキュメントでは、トリアージプロセスと、現在のガイドラインと推奨事項について説明します。

ヒント

パッチを送信せずに貢献する方法を探しているなら、これがあなたにぴったりの分野かもしれません。Blackは人気のプロジェクトであるため、そのissueトラッカーは非常に混雑しており、常に利用可能な以上の注意が必要です。トリアージは最も華やかでも技術的に難しい貢献の形ではありませんが、それでも重要です。たとえば、古いバグレポートがまだ再現可能かどうかを知りたいと考えています！

このドキュメントをよく読んでから、issueに対応することで、簡単に始めることができます。

十分に貢献し、十分な時間滞在した場合は、トリアージ権限が与えられることもあります！

基本

Blackは、バグレポートからユーザーサポートの問題まで、さまざまなissueを受け取ります。トリアージとは、issueを特定し、整理し、解決までのライフサイクルにおけるissueの行程を開始することです。

より具体的には、issueをトリアージするということは

  • issueが属するタイプとカテゴリを特定する

  • バグを確認する

  • 必要に応じて質問/詳細情報を求める

  • 関連するissueをリンクする

  • 最初のフィードバック/サポートを提供する

トリアージは通常、issueへの最初の対応であるため、初期のトリアージ後にissueがあまり進展しなくても心配しないでください。トリアージの主な目的は、将来のより具体的な開発や議論のためにissueを準備することであるため、最終的に解決されます。

バグレポートまたはユーザーサポートissueのライフサイクルは、通常、次のようになります。

  1. issueはトリアージを待っています

  2. 特定済み - タイプラベルとその他の関連ラベルでマークされています。詳細情報や機能的な再現が必要な場合があります（そのため、S: needs reproまたはS: awaiting responseでマークする必要があります）

  3. 確認済み - issueを再現でき、必要な詳細情報が提供されています

  4. 議論中 - 初期のトリアージが完了し、issueを最適に解決する方法に関する一般的な詳細が検討されています

  5. 修正待ち - issueに関するさらなる議論は必要なく、解決のためのPRが次のステップです

  6. クローズ済み - issueが解決されました。理由は次のとおりです。

    • issueを再現できませんでした

    • issueが修正されました

    • 別の既存のissueの複製であるか、無効です

機能強化、ドキュメント、スタイルの問題の場合、ライフサイクルは非常に似ていますが、詳細は異なります。

  1. issueはトリアージを待っています

  2. 特定済み - タイプラベルとその他の関連ラベルでマークされています

  3. 議論中 - 提案された変更のメリットが現在議論されています。PRは受け入れられますが、拒否されるリスクが大きくなります

  4. 承認済み＆PR待ち - 提案された変更がOKであると判断され、PRが歓迎されます（S: accepted）

  5. クローズ済み - issueが解決されました。理由は次のとおりです。

    • 提案された変更が実装されました

    • 拒否されました（技術的な懸念事項、倫理的な矛盾など）

    • 既存のissueの複製であるか、無効です

注記: ドキュメントの問題は、拒否される可能性が低いため、現在S: acceptedラベルを使用していません。

ラベル付け

作業を整理、追跡し、効率的に作業を分担するためにラベルを使用します。

ラベルは、プレフィックスで識別されるいくつかのグループに分けられます。

  • T - タイプ: issue/PRの一般的な種類

  • C - カテゴリ: 問題の領域。バグの種類からプロジェクトのメンテナンスまで範囲があります

  • F - フォーマット領域: Cと似ていますが、フォーマット専用です

  • S - ステータス: このissueは現在解決のどの段階にありますか？

  • R - 解決方法: issue/PRはどうやって/なぜ解決されましたか？

いくつかのスタンドアロンラベルもあります。

  • good first issue: 初心者向けの問題（リポジトリを初めて訪れたユーザー向けのGitHubバナーに表示されます）

  • help wanted: かなりの作業が必要で、進捗のために多くの作業を求めている複雑なissue（さまざまなGitHubページにも表示されます）

  • skip news:些細でCHANGELOGエントリを必要としないPR用（CHANGELOGエントリチェックをスキップします）

注記

特にskip newsラベルについては、PRにラベルを使用していますが、それほど厳格ではありません。特定のPRにどのラベルが適切か（そもそも適切なラベルがあるか）については、自分の判断に従ってください。

プロジェクト

より一般的で広範な目標については、プロジェクトを使用して作業を追跡します。「素晴らしいドキュメント」プロジェクトなど、真の終わりがない長期的なプロジェクトもあれば、「ベータ版への移行」プロジェクトなど、より焦点を絞った明確な終わりを持つプロジェクトもあります。

注記

GitHubプロジェクトを変更するには、書き込みリポジトリ権限レベル以上が必要です。

issueのクローズ

issueをクローズすることは、issueがライフサイクルの終わりに達したことを意味するため、issueのクローズには注意が必要です。以下は、各タイプのissueに対する一般的な推奨事項です。これらはガイドラインにすぎず、判断が異なる場合は、代わりに従うことも完全に問題ありません。

ほとんどのissueの場合、解決策となるPRの後、手動または自動的にissueをクローズするのが理想的です。特にバグレポートの場合、バグが既に修正されている場合は、issueの送信者と連絡を取り、特定のケースが解決されたことを確認してからクローズしてください。mainブランチで修正された時点でissueをクローズすることに注意してください。必ずしもリリース済みであることを意味するわけではありません。

デザインと機能強化のissueも、多くの議論の後で決定されたか、単にBlackの理念に反するかどうかにかかわらず、提案された変更が実装されないことが明らかになった場合にクローズする必要があります。そのようなissueが激しくなる場合は、深刻な場合はクローズしてロックすることも許容されます（ただし、コアチームと連絡を取るのが良いアイデアです）。

ユーザーサポートissueは、作成者によって、またはissueが何らかの方法で解決されたことが明らかになった場合にクローズするのが最適です。

重複したissueと無効なissueは、目的がなく、既に混雑しているissueトラッカーにノイズを追加するため、常にクローズする必要があります。ただし、issueを重複としてラベル付けしてクローズする前に、それが本当に重複であり、単に非常に似ているだけではないことを確認してください。

よくあるレポート

BlackでフォーマットされたコードがE203メッセージの原因となるなど、頻繁に開かれるissueがいくつかあります。これらのissueは恐らく大いに重複している可能性がありますが、それでもトリアージが必要であり、他のものから貴重な時間を奪っています（ただし、トリアージでクローズされるため、通常はライフサイクルの大部分をスキップします）。

最も一般的なissueと、使用できる事前に作成された回答をいくつか紹介します。

「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.dokyumento.jp/en/stable/the_black_code_style/current_style.html#slices

Have a good day!