GitHub Issues連携機能の紹介
2020年5月6日 Alex Ross、@alexr00
Visual Studio Codeチームでは、すべての作業をGitHubのissueで追跡しています。詳細なイテレーション計画から個々のバグまで、すべてをGitHub issueとして追跡しています。issueが私たちのチームや他のGitHubプロジェクトにとって非常に重要であることを考えると、VS CodeにGitHub issueの統合機能を追加したいと考えました。この追加は、1年以上前に発表したGitHub Pull Requestの作業を補完するものです。VS Codeバージョン1.45以降、issueとソースコードをより密接に連携させるこの新しいサポートは、GitHub Pull Requests and Issues拡張機能 (以前の名称はGitHub Pull Requests) で利用可能になります。
当社の統合アプローチ
issueとプルリクエストは密接に関連しているため、これらを同じGitHub Pull Requests and Issues拡張機能に含めることは論理的なステップでした。これは、issueとプルリクエストの両方に同じGitHub APIの多くの部分が必要とされるためです。多くのソース管理オプションがあるため、GitHubの機能をVS Codeのコアエディターに直接追加することは望んでいませんでした。代わりに、ユーザーが開いているリポジトリがGitHubを使用していることを検出した場合に、この拡張機能を推奨します。独自の拡張機能APIを使用することで、APIが拡張機能の作成者が必要とする機能を備えていることを保証し、他のリポジトリプロバイダーも同様の統合を実装できるようになります。
特定のワークフローを過度に規定しないことが重要でした。代わりに、私たちの目標は、柔軟な方法でissueを内部開発ループに取り込むことでした。たとえば、コードコメントでissueにより多くのコンテキストを与えることはその目標の一部ですが、完全なissue管理をVS Codeに追加することはあまり適切ではありません。GitHubがすでに得意としているUIを再発明したくありません。まだ存在しない接続を確立したいと考えています。
コードコンテキストでのIssue
ソースコード内のissueへのリンクは、特に理解しにくいロジックがある場合や、対応が必要な`//TODO`コメントがある場合に、私たちのワークフローの通常の一部です。VS Codeリポジトリでissue参照を検索すると、多くのissueが言及されているのがわかります。リンクはより詳細な情報へのポインタを提供しますが、実際にさらに学ぶにはエディターを離れる必要がありました。しかし、ホバーでこのissueコンテキストを得ることで、作業の流れを中断することなく、さらに学ぶことができます。
issueホバーは、完全なissueのURL、issueコメントのURL、番号で参照されるissue (#1234)、およびowner/repository#1234で参照されるissue (例: Microsoft/vscode#1234) で機能します。また、コードベースではユーザーを参照することがよくあります。VS Codeの提案されたAPIには、提案の責任者が誰であるかを明確にするための開発者参照が多数含まれています。
issueコンテキストは通常、コミットが解決するissueを参照するためにコミットメッセージ内、ソースコードファイル内、およびMarkdown (変更履歴など) で必要とされます。このコンテキストを簡単に追加できるように、issueとユーザーの補完候補を追加しました。Gitコミットのテキストボックスでは、githubIssues.issueCompletionFormatScm設定を使用してissueの補完をフォーマットできます。Markdownファイルでは、issueはMarkdownリンクとして補完され、その他のファイルでは、単純なissue番号 (#1234) として補完されます。
可能なissueのリストはgithubIssues.queries設定で構成できるため、複数のリポジトリで作業している場合は、それらのissueのクエリを含めることができます。クエリはGitHub検索構文を使用します。ユーザーのリストには、現在開いているリポジトリのコラボレーターが含まれます。
どこからでもIssueを作成
VS Codeでソースコードを扱っている最中にバグを発見した場合、issueを作成し、その領域の担当者に割り当てます。または、バグの発見者が担当者でもある場合、後で戻るためのリマインダーとして`//TODO`コメントを残すことがよくあります。コードベース全体に`//TODO`が散らばっていると、多くの貢献者がいる場合に追跡が困難になります（誰もが経験していることですが）。しかし、issueを作成し、それを`//TODO`で参照することで追跡可能になります。ソースコードの奥深くにいるときにissueを作成する際の障壁とコンテキストの喪失を減らすために、いくつかの新しいissue作成方法があります。
`//TODO`コメントから (githubIssues.createIssueTriggersで設定可能)、VS Codeを離れることなくissueを作成し、割り当てることができます。
また、選択範囲から、GitHub Issues: Create Issue from Selectionコマンドを使用して、元のソースコードへのパーマリンク付きでissueを素早く作成できます。コードへの参照が必要な場合は、GitHub Issues: Copy GitHub Permalinkコマンドも使用できます。最後に、ターミナルにエラー情報がある場合は、その出力をクリップボードにコピーし、GitHub Issues: Create Issue from Clipboardを使用してissueを作成できます。
Issueでの作業
一般的なワークフローは、issueを確認し、作業するものを選択し、作業用のブランチを作成し、コミットを行い、その後プルリクエストで変更をmainにマージするというものです。新しいIssuesビューから、まさにこれを行うことができます。
より多くのワークフローに対応するため、いくつかのオプションを設定できます。トピックブランチの作成を伴わないワークフローの場合、githubIssues.useBranchForIssuesでブランチ作成を無効にできます。ブランチに異なる命名規則がある場合は、githubIssues.issueBranchTitle設定を使用できます。Issuesビューにリストされるissueは、githubIssues.queriesを使用してカスタムクエリを使用するように構成できます。
さらに詳しく知りたいですか？
Sana Ajani (@sana_ajani) と Burke Holland (@burkeholland) によるGitHub Satelliteでの「すべてのGitHubユーザーがVS Codeについて知っておくべきこと」と題された講演をご覧いただけます。
また、VS CodeのGitHub統合についてより詳細に説明しているGitHubとの連携トピックも参照できます。
今後の展望
現在、これらの機能のほとんどはリポジトリのクローンでのみサポートされており（フォークではサポートされていません）、そのため、それらや他のユースケースをサポートするためにはさらなる作業が必要です。この拡張機能に対するフィードバックをお待ちしておりますので、拡張機能のリポジトリのissueに遠慮なくご提案ください！
ハッピーコーディング！
Alex Ross、VS Code開発者 @alexr00