自動化とトリアージプロセス

このドキュメントでは、IssueとPull Requestを管理・トリアージするために使用している自動化プロセスについて詳しく説明します。私たちの目標は、迅速なフィードバックを提供し、コントリビューションが効率的にレビュー・統合されるようにすることです。この自動化の仕組みを理解することで、コントリビューターとしてのあなたが何を期待すべきか、そしてリポジトリのbotとどうやってうまくやり取りできるかがわかるようになります。

基本原則: Issues と Pull Requests

まず最初に重要なのは、ほぼすべてのPull Request (PR) は対応するIssueにリンクされているべきだということです。Issueは「何をするのか」と「なぜそれをするのか」（バグや機能）を記述し、PRは「どのように実装するか」を示します。この分離により、作業の追跡、機能の優先順位付け、明確な履歴の維持が可能になります。私たちの自動化はこの原則に基づいて構築されています。

詳細な自動化ワークフロー

以下は、私たちのリポジトリで実行されている具体的な自動化ワークフローの内訳です。

1. Issue を作成するとき: Automated Issue Triage

Issue を作成した際に最初にやり取りする bot です。この bot の役割は、Issue の初期分析を行い、適切なラベルを適用することです。

• Workflow ファイル: .github/workflows/gemini-automated-issue-triage.yml
• 実行タイミング: Issue が作成または再オープンされた直後
• 処理内容:
  • Gemini モデルを使用して、Issue のタイトルと本文を詳細なガイドラインに基づいて分析します。
  • area/* ラベルを 1 つ適用: Issue をプロジェクトの機能領域に分類します（例: area/ux, area/models, area/platform）。
  • kind/* ラベルを 1 つ適用: Issue の種別を識別します（例: kind/bug, kind/enhancement, kind/question）。
  • priority/* ラベルを 1 つ適用: 説明された影響度に基づいて、P0（クリティカル）から P3（低）までの優先度を割り当てます。
  • status/need-information を適用する場合があります: Issue にログや再現手順など重要な情報が欠けている場合、追加情報の提供を促すフラグが立てられます。
  • status/need-retesting を適用する場合があります: Issue で参照されている CLI のバージョンが 6 世代以上古い場合、現在のバージョンでの再テストを促すフラグが立てられます。
• あなたに求められること:
  • Issue テンプレートにできるだけ詳細に記入してください。提供される情報が多ければ多いほど、トリアージの精度が向上します。
  • status/need-information ラベルが付与された場合は、コメント欄に要求された情報を追加してください。

2. Pull Request を開いたとき: Continuous Integration (CI)

このワークフローは、すべての変更がマージされる前に品質基準を満たしていることを保証します。

• Workflow File: .github/workflows/ci.yml
• 実行タイミング: Pull Request へのすべての push 時に実行されます。
• 処理内容:
  • Lint: コードがプロジェクトのフォーマットおよびスタイルルールに準拠しているかをチェックします。
  • Test: macOS、Windows、Linux 上および複数の Node.js バージョンで、自動テストスイート全体を実行します。これは CI プロセスの中で最も時間がかかる部分です。
  • Post Coverage Comment: すべてのテストが正常にパスした後、Bot が PR にコメントを投稿します。このコメントには、変更内容がテストでどれだけカバーされているかのサマリーが記載されています。
• あなたがすべきこと:
  • すべての CI チェックがパスすることを確認してください。すべてが成功すると、コミットの横に緑色のチェックマーク ✅ が表示されます。
  • チェックが失敗した場合（赤い “X” ❌）、失敗したチェックの横にある「Details」リンクをクリックしてログを確認し、問題を特定して修正を push してください。

3. Pull Request の継続的なトリアージ: PR Auditing and Label Sync

このワークフローは定期的に実行され、すべてのオープンな PR が正しく issue にリンクされ、一貫したラベルが付与されていることを確認します。

• Workflow ファイル: .github/workflows/gemini-scheduled-pr-triage.yml
• 実行タイミング: 15分ごとに、すべてのオープンな pull request に対して実行されます。
• 処理内容:
  • リンクされた issue の確認: bot は PR の description から issue にリンクするキーワード（例: Fixes #123、Closes #456）をスキャンします。
  • status/need-issue の追加: リンクされた issue が見つからない場合、bot は PR に status/need-issue ラベルを追加します。これは、issue の作成およびリンクが必要であることを明確に示すサインです。
  • ラベルの同期: issue がリンクされている場合、bot は PR のラベルが issue のラベルと完全に一致するようにします。不足しているラベルがあれば追加し、不要なラベルは削除します。また、status/need-issue ラベルが付与されていれば削除します。
• あなたに必要な対応:
  • 常に PR を issue にリンクしてください。 これが最も重要なステップです。PR の description に Resolves #<issue-number> のような行を追加してください。
  • これにより、PR が正しく分類され、レビュープロセスがスムーズに進むようになります。

4. Issues の継続的トリアージ: Scheduled Issue Triage

これは、どの Issue もトリアージプロセスから漏れることのないようにするためのフォールバック・ワークフローです。

• Workflow ファイル: .github/workflows/gemini-scheduled-issue-triage.yml
• 実行タイミング: すべてのオープン状態の Issue に対して、1時間ごとに実行
• 処理内容:
  • ラベルがまったくない、またはまだ status/need-triage ラベルがついている Issue を積極的に検出します。
  • その後、初期トリアージボットと同じ強力な Gemini ベースの分析をトリガーして、適切なラベルを適用します。
• あなたが行うべきこと:
  • 通常は何もする必要はありません。このワークフローは、初期トリアージが失敗した場合でも、すべての Issue が最終的にカテゴリ分けされるようにするための安全装置です。

5. リリース自動化

このワークフローは、Qwen Code の新しいバージョンをパッケージングし、公開するプロセスを管理します。

• ワークフローファイル: .github/workflows/release.yml
• 実行タイミング: 「nightly」リリースのための日次スケジュール、および公式のパッチ/マイナーリリースのための手動実行。
• 処理内容:
  • プロジェクトを自動ビルドし、バージョン番号を更新して、npm にパッケージを公開します。
  • 自動生成されたリリースノートとともに、GitHub に該当するリリースを作成します。
• あなたがすべきこと:
  • コントリビューターとして、このプロセスに対して何もする必要はありません。PR が main ブランチにマージされたら、あなたの変更が次の nightly リリースに確実に含まれることを安心してください。

この詳細な概要が役立つことを願っています。自動化やプロセスについて質問がある場合は、遠慮なくお尋ねください！