GitHub Issues との統合の概要

Name: Visual Studio Code
Author: Microsoft

2020年5月6日 by Alex Ross, @alexr00

Visual Studio Code チームでは、すべての作業を追跡するために GitHub Issues を使用しています。詳細なイテレーション計画から個々のバグまで、すべてを GitHub Issues として追跡しています。私たちのチームや他の GitHub プロジェクトにとって Issues がいかに重要であるかを考え、VS Code に GitHub Issues の統合機能を追加したいと考えました。この追加は、1年以上前に発表した GitHub Pull Request の作業を補完するものです。VS Code バージョン 1.45 から、この新しいサポートにより Issues とソースコードをより緊密に連携させることができ、GitHub Pull Requests and Issues 拡張機能（旧称 GitHub Pull Requests）で利用可能になります。

私たちの統合アプローチ

Issues とプルリクエストは密接に関連していることが多いため、同じ GitHub Pull Requests and Issues 拡張機能に含めることは論理的なステップでした。Issues とプルリクエストの両方に同じ GitHub API の多くが必要だからです。私たちは、ソース管理には多くの選択肢があるため、GitHub 機能を VS Code エディターのコアに直接追加したくありませんでした。代わりに、ユーザーが開いているリポジトリが GitHub を使用していることを検出した場合に、この拡張機能を推奨します。私たち自身の拡張機能 API を使用することで、API が拡張機能作成者に必要な機能を備えていることを保証し、他のリポジトリプロバイダーも同様の統合を実装できます。

過度に特定のワークフローを規定しないことが重要でした。代わりに、私たちの目標は、柔軟な方法で Issues を開発の内部ループに取り込むことでした。たとえば、コードコメントで Issue のコンテキストを増やすことはその目標の一部ですが、完全な Issue 管理を VS Code に追加することはあまり適合しません。私たちは GitHub が既にうまくやっている UI を再発明したくありません。私たちは、まだ存在しないつながりを作りたいと考えています。

コードコンテキスト内の Issues

ソースコード内の Issues へのリンクは、私たちのワークフローの通常の一部です。特に、理解が難しいロジックがある場合や、対応が必要な //TODO コメントがある場合にそうです。VS Code リポジトリで Issue 参照の検索を行うと、たくさんの Issue が言及されているのがわかります。リンクは詳細情報へのポインターを提供しますが、実際に詳細を知るにはエディターを離れる必要があります。今では、ホバーでこの Issue のコンテキストを得ることで、流れを中断することなく詳細を知ることができます。

Issue Hover

Issue ホバーは、完全な Issue の URL、Issue コメントの URL、番号で参照される Issue（#1234）、owner/repository#1234（例：Microsoft/vscode#1234）で参照される Issue で機能します。また、コードベース内でユーザーを頻繁に参照します。VS Code の提案 API には、提案の責任者を明確にするために多くの開発者参照が含まれています。

User Hover

Issue のコンテキストは、コミットが解決する Issue を参照するためのコミットメッセージ内、ソースコードファイル内、および Markdown（変更ログなど）で通常必要とされます。このコンテキストを簡単に追加するために、Issue とユーザーの補完候補を追加しました。Git のコミットテキストボックスでは、githubIssues.issueCompletionFormatScm 設定で Issue 補完の書式を設定できます。Markdown ファイルでは、Issue は Markdown リンクとして補完され、他のファイルでは、Issue は単純な Issue 番号（#1234）として補完されます。

Completion Suggestions

考えられる Issue のリストは githubIssues.queries 設定で構成可能なので、複数のリポジトリにまたがって作業する場合、それらの Issue のクエリを含めることができます。クエリは GitHub の検索構文を使用します。ユーザーのリストには、現在開いているリポジトリのコラボレーターが含まれます。

Issue Queries

どこからでも Issue を作成

ソースコードの作業中に VS Code でバグを見つけた場合、私たちは Issue を作成し、その領域の担当者に割り当てます。あるいは、バグの発見者が担当者でもある場合、後で戻ってくるためのリマインダーとして //TODO コメントを残すことがよくあります。多くの貢献者がいる場合、コードベース全体に //TODO が散らばっていると追跡が困難になりますが（私たち全員が経験したことがあると言っても過言ではありません）、Issue を作成して //TODO で参照すれば追跡可能です。ソースコードの奥深くで Issue を作成する際の障壁とコンテキストの損失を減らすために、Issue を作成するためのいくつかの新しい方法があります。

//TODO コメントから（githubIssues.createIssueTriggers で設定可能）、VS Code を離れることなく Issue を作成し、割り当てることができます。

Create Issue from TODO

そして、選択範囲から、GitHub Issues: Create Issue from Selection コマンドを使用して、元のソースコードへのパーマリンク付きの Issue を素早く作成できます。コードへのポインターが必要なだけなら、GitHub Issues: Copy GitHub Permalink コマンドも使用できます。最後に、ターミナルに失敗情報がある場合は、出力をクリップボードにコピーして GitHub Issues: Create Issue from Clipboard を使用して Issue を作成するだけです。

Issues の作業

一般的なワークフローは、自分の Issues を確認し、作業するものを1つ選び、作業用のブランチを作成し、いくつかのコミットを行い、その後プルリクエストで変更を main にマージするというものです。新しい Issues ビューから、まさにそれができます。

Work on an Issue

より多くのワークフローに適合させるために、設定できるいくつかのオプションがあります。トピックブランチの作成を伴わないフローの場合は、githubIssues.useBranchForIssues でブランチ作成を無効にできます。ブランチに異なる命名規則がある場合は、githubIssues.issueBranchTitle 設定を使用できます。Issues ビューにリストされる Issues は、githubIssues.queries を使用してカスタムクエリを使用するように設定できます。

もっと詳しく知りたいですか？

Sana Ajani (@sana_ajani) と Burke Holland (@burkeholland) による GitHub Satellite での「What every GitHub user should know about VS Code (すべての GitHub ユーザーが VS Code について知っておくべきこと)」の講演をご覧いただけます。

また、GitHub の操作のトピックを読むこともできます。ここでは VS Code の GitHub 統合について詳しく説明しています。

今後の展望

現在、これらの機能のほとんどはリポジトリのクローン（フォークではない）でのみサポートされているため、フォークやその他のユースケースをサポートするためにはまだやるべきことがあります。この拡張機能に対するフィードバックをお待ちしておりますので、拡張機能のリポジトリの Issues に提案をお気軽にお寄せください！

ハッピーコーディング！

Alex Ross, VS Code 開発者 @alexr00