介紹 GitHub Issues 整合

Name: Visual Studio Code
Author: Microsoft

2020年5月6日，由 Alex Ross (@alexr00) 撰寫

在 Visual Studio Code 團隊，我們使用 GitHub issues 來跟蹤我們的所有工作。從詳細的迭代計劃到個別 bug，我們都透過 GitHub issues 進行跟蹤。鑑於 issues 對我們團隊和其他 GitHub 專案的重要性，我們希望將 GitHub issues 整合到 VS Code 中。這項新功能補充了我們一年多前宣佈的 GitHub Pull Request 功能。從 VS Code 1.45 版本開始，這項旨在將 issues 和原始碼更緊密結合的新支援將在 GitHub Pull Requests and Issues 擴充套件（原名為 GitHub Pull Requests）中提供。

我們的整合方法

Issues 和 pull requests 通常是相輔相成的，因此將它們包含在同一個 GitHub Pull Requests and Issues 擴充套件中是合乎邏輯的一步，因為 issues 和 pull requests 都需要使用許多相同的 GitHub API。我們不希望直接在 VS Code 編輯器核心中新增 GitHub 功能，因為有許多原始碼控制選項。取而代之的是，當我們檢測到使用者開啟的倉庫使用 GitHub 時，我們會推薦該擴充套件。透過使用我們自己的擴充套件 API，我們確保了 API 具備擴充套件作者所需的功能，並且其他倉庫提供商也可以實現類似的整合。

對我們來說，不規定過於具體的工作流程非常重要。相反，我們的目標是以一種靈活的方式將 issues 引入到內部開發迴圈中。例如，在程式碼註釋中為 issue 提供更多上下文是該目標的一部分，但在 VS Code 中新增完整的 issue 管理功能則不太適合。我們不想重新發明 GitHub 已經做得很好的 UI。我們真正想做的是建立那些尚不存在的聯絡。

程式碼上下文中的 Issues

在原始碼中連結到 issues 是我們工作流程的常規部分，尤其是在某些邏輯難以理解或有需要採取行動的 //TODO 註釋時。如果你在 VS Code 倉庫中搜尋 issue 引用，你會看到大量被提及的 issues。雖然連結提供了指向更多資訊的指標，但要真正瞭解更多資訊，你需要離開編輯器。現在，透過懸停提示獲得 issue 的上下文，你無需中斷流程即可瞭解更多資訊。

Issue Hover

Issue 懸停提示適用於完整的 issue URL、issue 評論 URL、透過編號引用的 issues (#1234) 以及透過 owner/repository#1234 引用的 issues（例如 Microsoft/vscode#1234）。我們也經常在程式碼庫中引用使用者。VS Code 的提案 API 中有許多開發人員的引用，以明確誰對這些提案負責。

User Hover

通常，在提交資訊中引用 issue 來表明該次提交解決了哪個問題，在原始碼檔案和 Markdown（例如更新日誌）中也需要 issue 的上下文。為了輕鬆新增這種上下文，我們為 issues 和使用者添加了自動補全建議。在 Git 提交文字框中，你可以使用 githubIssues.issueCompletionFormatScm 設定來格式化你的 issue 自動補全。在 Markdown 檔案中，issue 會自動補全為 Markdown 連結；在其他檔案中，issue 會自動補全為簡單的 issue 編號 (#1234)。

Completion Suggestions

可能的 issues 列表可以透過 githubIssues.queries 設定進行配置，因此如果你跨多個倉庫工作，可以包含對這些 issues 的查詢。這些查詢使用 GitHub 搜尋語法。使用者列表包括當前開啟的倉庫中的協作者。

Issue Queries

從任何地方建立 issue

當我們在處理某些原始碼時發現 VS Code 中的一個 bug，我們會建立一個 issue 並將其分配給負責該區域的人。或者，如果 bug 的發現者也是負責人，我們通常會留下一條 //TODO 註釋作為提醒，以便稍後處理。當貢獻者眾多時，分散在整個程式碼庫中的 //TODO 很難跟蹤（儘管可以肯定地說我們都這麼做過），但建立一個 issue 並在 //TODO 中引用它，就可以被跟蹤了。為了在深入研究原始碼時減少建立 issue 的障礙和上下文丟失，我們提供了幾種建立 issues 的新方法。

透過 //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，選擇一個來處理，建立一個分支來進行工作，進行一些提交，然後透過 pull request 將你的更改合併回主分支。透過新的 **Issues** 檢視，你就可以做到這一點。

Work on an Issue

為了適應更多的工作流程，你可以配置幾個選項。如果你的流程不涉及建立主題分支，你可以使用 githubIssues.useBranchForIssues 停用分支建立。如果你的分支有不同的命名方案，你可以使用 githubIssues.issueBranchTitle 設定。**Issues** 檢視中列出的 issues 可以透過 githubIssues.queries 配置為使用自定義查詢。

想了解更多嗎？

你可以觀看 Sana Ajani (@sana_ajani) 和 Burke Holland (@burkeholland) 在 GitHub Satellite 大會上帶來的**《每個 GitHub 使用者都應瞭解的 VS Code 知識》**演講。

你還可以閱讀與 GitHub 協作主題，其中更詳細地描述了 VS Code 的 GitHub 整合。

未來展望

目前，這些功能中的大多數僅在倉庫克隆（而不是 fork）中受支援，因此還需要做更多的工作來支援該用例和其他用例。我們非常希望看到你對這個擴充套件的反饋，歡迎隨時在擴充套件的倉庫中給我們留下建議！

編碼愉快！

Alex Ross，VS Code 開發者 @alexr00