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

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

基本方針：Issue と Pull Request

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

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

以下に、リポジトリで実行される具体的な自動化ワークフローの内訳を示します。

1. Issue を作成したとき：Automated Issue Triage

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

• ワークフローファイル: .github/workflows/qwen-automated-issue-triage.yml
• 実行タイミング: Issue が作成または再オープンされた直後。
• 動作内容:
  • Qwen モデルを使用して、詳細なガイドラインに基づき 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 を適用する場合あり: ログや再現手順などの重要な詳細が不足している場合、追加情報のフラグが立てられます。
  • status/need-retesting を適用する場合あり: 参照されている CLI バージョンが 6 バージョン以上古い場合、最新バージョンでの再テストのフラグが立てられます。
• 実施すべきこと:
  • Issue テンプレートに可能な限り詳細に入力してください。提供される情報が多いほど、トリアージの精度が向上します。
  • status/need-information ラベルが追加された場合は、コメントで要求された詳細情報を提供してください。

2. Pull Request を作成したとき：Continuous Integration (CI)

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

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

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

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

• ワークフローファイル: .github/workflows/qwen-scheduled-pr-triage.yml
• 実行タイミング: オープン状態のすべての Pull Request に対して 15 分ごと。
• 動作内容:
  • リンクされた Issue の確認: ボットが PR の説明をスキャンし、Issue へのリンクキーワード（例：Fixes #123、Closes #456）を検索します。
  • status/need-issue の追加: リンクされた Issue が見つからない場合、ボットは PR に status/need-issue ラベルを追加します。これは Issue の作成とリンクが必要であることを明確に示すシグナルです。
  • ラベルの同期: Issue がリンクされている場合、ボットは PR のラベルが Issue のラベルと完全に一致するようにします。不足しているラベルは追加され、不要なラベルは削除されます。また、status/need-issue ラベルが存在する場合は削除されます。
• 実施すべきこと:
  • 必ず PR を Issue にリンクしてください。 これが最も重要なステップです。PR の説明に Resolves #<issue-number> のような行を追加してください。
  • これにより、PR が正しく分類され、レビュープロセスをスムーズに進めることができます。

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

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

• ワークフローファイル: .github/workflows/qwen-scheduled-issue-triage.yml
• 実行タイミング: オープン状態のすべての Issue に対して 1 時間ごと。
• 動作内容:
  • ラベルが全く付いていない Issue、または status/need-triage ラベルが付いたままの Issue を積極的に検出します。
  • その後、初期トリアージボットと同じ強力な Qwen Code ベースの分析をトリガーし、適切なラベルを適用します。
• 実施すべきこと:
  • 通常、特に操作は必要ありません。このワークフローは、初期トリアージが失敗した場合でも、すべての Issue が最終的に分類されるようにするためのセーフティネットです。

5. リリース自動化

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

• ワークフローファイル: .github/workflows/release.yml
• 実行タイミング: 「nightly」リリースは毎日スケジュール実行、公式の patch/minor リリースは手動実行。
• 動作内容:
  • プロジェクトの自動ビルド、バージョン番号の更新、npm へのパッケージ公開を行います。
  • 生成されたリリースノートを含む対応するリリースを GitHub 上に作成します。
• 実施すべきこと:
  • コントリビューターとして、このプロセスに対して特に操作を行う必要はありません。PR が main ブランチにマージされれば、変更内容は次の nightly リリースに確実に含まれます。

本ドキュメントが皆様のお役に立てば幸いです。自動化やプロセスについてご質問がある場合は、お気軽にお問い合わせください。