チケットのトリアージ—Djangoドキュメント
チケットのトリアージ
Djangoは、コードベースでの作業を管理するために Trac を使用します。 Tracは、人々が見つけたバグと人々が追加してほしい機能のコミュニティ向けの庭です。 他の庭と同じように、引っ張る雑草があることもあれば、摘む必要のある花や野菜があることもあります。 私たちはお互いを整理するためにあなたの助けを必要としています、そして最終的に私たちは皆一緒に利益を得ます。
すべての庭園と同様に、私たちは完璧を目指すことができますが、実際にはそのようなことはありません。 最も手付かずの庭でさえ、カタツムリや昆虫がまだいます。 コミュニティガーデンには、最善を尽くして雑草を肥やし、バラを毒殺する親切な人々もいます。 コミュニティ全体の仕事は、自己管理し、問題を最小限に抑え、コミュニティに参加する人々を教育して、貴重な貢献メンバーになることができるようにすることです。
同様に、TracがDjangoの進捗状況を完全に表すことを目指していますが、これは起こらないことを認識しています。 Tracのメンテナンスの負荷をコミュニティに分散することで、間違いが発生することを受け入れます。 Tracは「ほぼ正確」であり、時々間違っているという事実を考慮に入れています。 大丈夫。 私たちは締め切りのある完璧主義者です。
私たちはコミュニティに参加を続け、チケットを可能な限り正確に保ち、混乱や意見の不一致がある場合はメーリングリストで議論するための問題を提起します。
Djangoはコミュニティプロジェクトであり、すべての貢献が役立ちます。 あなたなしではこれはできません!
トリアージワークフロー
残念ながら、チケットトラッカーのすべてのバグレポートと機能リクエストが必要な詳細をすべて提供しているわけではありません。 多くのチケットにはパッチがありますが、それらのパッチは良いパッチのすべての要件を満たしていません。
支援する1つの方法は、他のユーザーによって作成されたトリアージチケットを使用することです。
ワークフローのほとんどは、チケットのトリアージステージの概念に基づいています。 各ステージは、その存続期間中、特定のチケットがいつでもどこにあるかを記述します。 この属性は、いくつかのフラグに加えて、各チケットが何を誰が待っているかを簡単に示します。
写真は千の言葉の価値があるので、そこから始めましょう:
[[Django/docs/3.0.x/_images/triage_process|[[File:../../_images/triage_process.svg|400x501px|Django's ticket triage workflow]]]] この図には2つの役割があります。
- コミッター:パッチをマージする最終決定を行う責任があるコミットアクセス権を持つ人々。
- チケットトリアージャー:Djangoの開発プロセスに参加することを選択したDjangoコミュニティの誰でも。 Tracのインストールは意図的に公開されており、誰でもチケットを優先順位付けできます。 Djangoはコミュニティプロジェクトであり、コミュニティによるトリアージをお勧めします。
例として、ここでは平均的なチケットのライフサイクルを示しています。
- アリスはチケットを作成し、不完全なプルリクエストを送信します(テストなし、誤った実装)。
- ボブはプルリクエストを確認し、チケットに「承認済み」、「テストが必要」、「パッチの改善が必要」のマークを付け、パッチを改善する方法をアリスに伝えるコメントを残します。
- アリスはプルリクエストを更新し、テストを追加します(ただし、実装は変更しません)。 彼女は2つのフラグを削除します。
- チャーリーはプルリクエストを確認し、実装の改善に関する別のコメントで「パッチには改善が必要」フラグをリセットします。
- アリスはプルリクエストを更新し、実装を修正します。 彼女は「パッチには改善が必要」フラグを削除します。
- デイジーはプルリクエストを確認し、チケットを「チェックインの準備ができました」とマークします。
- コミッターのJacobは、プルリクエストを確認してマージします。
一部のチケットはこれよりもはるかに少ないフィードバックを必要としますが、それでも一部のチケットははるかに多くを必要とします。
トリアージ段階
以下では、チケットがその存続期間中に流れる可能性のあるさまざまな段階について詳しく説明します。
未レビュー
チケットに有効な問題、実行可能な機能が含まれているかどうか、またはさまざまな理由でチケットを閉じる必要があるかどうかを判断する資格があると感じた人は、チケットをレビューしていません。
承認済み
大きな灰色の領域! 「承認済み」の絶対的な意味は、チケットに記載されている問題が有効であり、作業のある段階にあることです。 それ以外にも、いくつかの考慮事項があります。
承認済み+フラグなし
チケットは有効ですが、まだ誰もパッチを提出していません。 多くの場合、これは、パッチの作成を安全に開始できることを意味します。 これは一般に、受け入れられた機能よりも受け入れられたバグの場合に当てはまります。 受け入れられたバグのチケットは、問題が少なくとも1人のトリアージによって正当なバグとして確認されたことを意味し、可能であれば修正する必要があります。 受け入れられた新機能は、1人のトリアージがその機能があればよいと考えたことを意味するだけかもしれませんが、これだけではコンセンサスビューを表すものではなく、その機能のパッチが受け入れられることを確実に意味するものでもありません。 疑問がある場合は、広範なパッチを作成する前に、さらにフィードバックを求めてください。
承認済み+パッチあり
チケットは、提供されたパッチをレビューする人々を待っています。 これは、パッチをダウンロードして試してみ、テストとドキュメントが含まれていることを確認し、含まれているパッチを使用してテストスイートを実行し、チケットにフィードバックを残すことを意味します。
承認済み+パッチあり+ニーズ…
これは、チケットが確認され、さらに作業が必要であることが判明したことを意味します。 「テストが必要」と「ドキュメントが必要」は一目瞭然です。 「パッチには改善が必要」には、通常、コードを改善するために何が必要かを説明するチケットへのコメントが付いています。
チェックインの準備ができました
チケットは、パッチを提供した人以外のコミュニティのメンバーによってレビューされ、コミット対応パッチのすべての要件を満たしていることがわかりました。 コミッターは、コミットする前にパッチに最終レビューを行う必要があります。 「私のチケットは永遠にRFCにあります!」については、新しい寄稿者のFAQ を参照してください。 私は何をすべきか?"
いつか/たぶん
この段階は図には示されていません。 高レベルのアイデアや長期的な機能のリクエストを追跡するために、控えめに使用されています。
これらのチケットは、具体的な実行可能な問題を説明していないため、一般的ではなく、全体的にあまり役に立ちません。 これらは、優れたパッチが提出された場合にフレームワークにいつか追加することを検討する可能性のある拡張リクエストです。 それらは優先度が高くありません。
その他のトリアージ属性
Tracでチェックボックスとして表示されるいくつかのフラグは、チケットに設定できます。
パッチがあります
これは、チケットにパッチが関連付けられていることを意味します。 これらは、パッチが「良好」であるかどうかを確認するためにレビューされます。
次の3つのフィールド(ドキュメントが必要、テストが必要、パッチの改善が必要)は、パッチが提供されている場合にのみ適用されます。
ドキュメントが必要
このフラグは、関連するドキュメントが必要なパッチのあるチケットに使用されます。 機能をコードベースにチェックインする前に、機能の完全なドキュメントが前提条件です。
テストが必要
これにより、パッチに関連する単体テストが必要であるというフラグが立てられます。 繰り返しますが、これは有効なパッチの必須部分です。
パッチの改善が必要
このフラグは、チケットにパッチがありますが、チェックインの準備が整っていないことを意味します。 これは、パッチが正しく適用されなくなったか、実装に欠陥があるか、コードが標準を満たしていないことを意味している可能性があります。
簡単なピッキング
小さくて簡単なパッチが必要なチケット。
タイプ
チケットは、タイプによって次のように分類する必要があります。
- *; 新機能
- 何か新しいものを追加するため。
- *; バグ
- 既存のものが壊れているか、期待どおりに動作していない場合に使用します。
- *; クリーンアップ/最適化
- 何も壊れていないが、何かをよりきれいに、より良く、より速く、より強くすることができるときのために。
成分
チケットは、コンポーネントに分類して、Djangoコードベースのどの領域に属しているかを示す必要があります。 これにより、チケットがより適切に整理され、見つけやすくなります。
重大度
everity 属性は、ブロッカー、つまり、次のバージョンのDjangoをリリースする前に修正する必要がある問題を識別するために使用されます。 通常、これらの問題は、以前のバージョンからのリグレッションを引き起こしたり、深刻なデータ損失を引き起こす可能性のあるバグです。 この属性が使用されることはめったになく、チケットの大部分の重大度は「通常」です。
バージョン
version 属性を使用して、報告されたバグが特定されたバージョンを示すことができます。
UI / UX
このフラグは、ユーザーインターフェイスとユーザーエクスペリエンスの質問に関連するチケットに使用されます。 たとえば、このフラグは、フォームまたは管理インターフェイスのユーザー向け機能に適しています。
Cc
このフィールドにユーザー名または電子メールアドレスを追加して、チケットに新しい寄付が行われたときに通知を受けることができます。
キーワード
このフィールドを使用すると、チケットに複数のキーワードでラベルを付けることができます。 これは、たとえば、同じテーマの複数のチケットをグループ化する場合に役立ちます。 キーワードは、コンマまたはスペースで区切ることができます。 キーワード検索では、キーワード内の任意の場所でキーワード文字列が検索されます。 たとえば、キーワード「form」のチケットをクリックすると、「formset」、「modelformset」、「ManagementForm」などの文字列を含むキーワードでタグ付けされた同様のチケットが生成されます。
クロージングチケット
チケットがその有用なライフサイクルを完了したら、それは閉じられる時です。 ただし、チケットを閉じることは大きな責任です。 問題が本当に解決されていることを確認する必要があります。また、チケットのレポーターは、チケットを閉じてもらえない可能性があることに注意する必要があります(もちろん、修正されていない限り)。 チケットを閉じることに確信が持てない場合は、代わりに自分の考えをコメントに残してください。
チケットを閉じる場合は、常に次のことを確認する必要があります。
- 問題が解決されていることを確認してください。
- チケットを閉じる決定を説明するコメントを残してください。
- チケットを改善して再開する方法がある場合は、そのことを知らせてください。
- チケットが重複している場合は、元のチケットを参照してください。 また、元のチケットにコメントを残して、クローズされたチケットを相互参照します。これにより、報告されたバグまたは要求された機能に関するより関連する情報にアクセスできます。
- 礼儀正しくしてください。チケットを閉じるのが好きな人はいません。 それはイライラすることもあれば、落胆させることさえあります。 人々がDjangoに貢献することをやめさせないための最善の方法は、礼儀正しく友好的であり、このチケットや他のチケットを将来改善する方法について提案することです。
チケットはいくつかの方法で解決できます。
- *; 修繕
- パッチがDjangoにロールインされ、問題が修正された後に使用されます。
- *; 無効
- チケットが正しくないことが判明した場合に使用されます。 これは、チケットの問題が実際にはユーザーエラーの結果であるか、Django以外の問題を説明しているか、バグレポートや機能リクエストではないことを意味します(たとえば、一部の新しいユーザーは次のようにサポートクエリを送信します切符売場)。
- *; wontfix
- 誰かがリクエストがDjangoでの検討に適切でないと判断した場合に使用されます。 チケットを閉じた人の論理的根拠とは異なると感じた場合、 django-developers メーリングリストでのディスカッションを開始するようにレポーターに要求して、チケットが「wontfix」として閉じられることがあります。 また、チケットを閉じる決定の前に、メーリングリストのディスカッションが行われることもあります。 「wontfix」としてクローズされたチケットを再開する前に、常にメーリングリストを使用してコンセンサスを取得してください。
- *; 複製
- 別のチケットが同じ問題をカバーしている場合に使用されます。 重複するチケットを閉じることで、すべてのディスカッションを1か所にまとめ、すべての人を支援します。
- *; worksforme
- チケットに元のバグを再現するのに十分な詳細が含まれていない場合に使用されます。
- *; needinfo
- 報告された問題を再現するのに十分な情報がチケットに含まれていないが、まだ有効である可能性がある場合に使用されます。 詳細情報が提供されたら、チケットを再開する必要があります。
チケットが誤ってクローズされたと思われる場合(まだ問題が発生している、別の場所にポップアップされている、またはトリアージャーがミスを犯しているなどの理由で)、チケットを再度開いて詳細情報を提供してください。 繰り返しになりますが、「wontfix」とマークされたチケットを再度開かず、代わりに django-developers に問題を報告してください。
トリアージをどのように支援できますか?
トリアージプロセスは、主にコミュニティメンバーによって推進されます。 本当に、 ANYONE が役に立ちます。
参加するには、 Trac でアカウントを作成することから始めます。 アカウントをお持ちでパスワードをお忘れの場合は、パスワードリセットページでリセットできます。
次に、次の方法で支援できます。
- 「未レビュー」チケットを「無効」、「worksforme」、「duplicate」、または「wontfix」として閉じる。
- 説明がまばらすぎて実行できない場合、または django-developers での議論が必要な機能リクエストの場合は、「未レビュー」チケットを「needsinfo」として閉じます。
- 正しく設定されていないチケットの「テストが必要」、「ドキュメントが必要」、または「パッチがあります」フラグを修正します。
- 小さくて比較的簡単なチケットに「 Easypickings 」フラグを設定します。
- まだ分類されていないチケットのタイプを設定します。
- 古いチケットがまだ有効であることを確認します。 チケットに長い間アクティビティが見られない場合は、問題は修正されているが、チケットはまだクローズされていない可能性があります。
- チケットのトレンドとテーマを特定します。 Djangoの特定の部分に関するバグレポートがたくさんある場合は、コードのその部分のリファクタリングを検討する必要があることを示している可能性があります。 トレンドが出現している場合は、 django-developers での議論(関連するチケットを参照)のためにそれを上げる必要があります。
- 他のユーザーから送信されたパッチが正しいかどうかを確認します。 それらが正しく、適切なドキュメントとテストが含まれている場合は、「チェックインの準備ができました」段階に移動します。 それらが正しくない場合は、コメントを残して理由を説明し、対応するフラグを設定します(「パッチには改善が必要」、「テストが必要」など)。
ノート
レポートページには、チケットの優先順位付けや上記のパッチの確認に役立ついくつかのクエリを含む、多くの便利なTracクエリへのリンクが含まれています。
また、新しい寄稿者へのアドバイスもあります。
ただし、チケットデータベースで作業しているすべての一般的なコミュニティメンバーには、次の質問をします。
- 自分のチケットを「チェックインの準備ができました」に宣伝しないでください。 レビューした他の人のチケットを「チェックインの準備ができました」としてマークすることはできますが、送信したパッチをレビューするには、少なくとも1人の他のコミュニティメンバーを取得する必要があります。
- コンセンサスを見つけるために django-developers にメッセージを投稿せずに、決定を取り消さないでください。
- 変更する必要があるかどうかわからない場合は、変更を加えずに、チケットに懸念事項をコメントとして残すか、 django-developers にメッセージを投稿してください。 確信が持てなくても大丈夫ですが、あなたの意見はそれでも価値があります。
回帰の二等分
リグレッションは、Djangoの新しいバージョンには存在するが、古いバージョンには存在しないバグです。 非常に役立つ情報は、リグレッションを導入したコミットです。 動作の変更を引き起こしたコミットを知ることは、変更が意図的なものであったのか、それとも不注意による副作用であったのかを特定するのに役立ちます。 これを判断する方法は次のとおりです。
この問題に対するDjangoのテストスイートの回帰テストを作成することから始めます。 たとえば、移行のリグレッションをデバッグしているふりをします。 テストを作成し、最新のマスターで失敗することを確認したら、スタンドアロンで実行できる別のファイルにテストを配置します。 この例では、tests/migrations/test_regression.py
を作成したと仮定します。これは次のコマンドで実行できます。
$ ./runtests.py migrations.test_regression
次に、テストが失敗したため、履歴の現在のポイントを「不良」としてマークします。
$ git bisect bad
You need to start by "git bisect start"
Do you want me to do it for you [Y/n]? y
ここで、回帰が導入される前にgit履歴内のポイントを見つける必要があります(つまり、 テストに合格するポイント)。 git checkout HEAD~100
のようなものを使用して、以前のリビジョンをチェックアウトします(この場合、100コミット前)。 テストが失敗するかどうかを確認します。 その場合は、そのポイントを「不良」(git bisect bad
)としてマークしてから、以前のリビジョンをチェックアウトして再チェックします。 テストに合格したリビジョンを見つけたら、それを「良好」としてマークします。
$ git bisect good
Bisecting: X revisions left to test after this (roughly Y steps)
...
これで、楽しい部分の準備が整いました。git bisect run
を使用して、残りのプロセスを自動化します。
$ git bisect run tests/runtests.py migrations.test_regression
git bisect
がバイナリ検索を使用して、テストが失敗した最初の「不良」コミットが見つかるまで、良好なコミットと不良なコミットの間のリビジョンを自動的にチェックアウトすることを確認する必要があります。
次に、Tracチケットで結果を報告し、回帰テストを添付ファイルとして含めてください。 誰かがバグの修正を書くとき、彼らはすでにあなたのテストを出発点として持っているでしょう。