介绍 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。我们不想将 GitHub 功能直接添加到 VS Code 核心编辑器中，因为有许多源代码控制选项。相反，当检测到用户的开放仓库使用 GitHub 时，我们将推荐该扩展。通过与我们自己的 extension API 合作，我们确保 API 具有扩展作者所需的功能，并且其他仓库提供程序可以实现类似的集成。

重要的是，我们不希望规定过于具体的流程。相反，我们的目标是以一种灵活的方式将 issues 引入到内部开发循环中。例如，为代码注释提供有关 issue 的更多上下文是该目标的一部分，但将完整的 issue 管理添加到 VS Code 中不太合适。我们不想重新发明 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 proposed API 包含许多开发人员引用，以便清楚地了解谁负责这些提案。

User Hover

通常需要在提交消息中、源代码文件中以及 Markdown 文件（例如 changelog）中需要 issue 上下文。为了轻松添加此上下文，我们已为 issues 和用户添加了补全建议。在 Git 提交文本框中，可以使用 githubIssues.issueCompletionFormatScm 设置格式化 issue 补全。在 Markdown 文件中，issues 会作为 Markdown 链接补全，在其他文件中，issues 会作为简单的 issue 编号 (#1234) 补全。

Completion Suggestions

可以使用 githubIssues.queries 设置配置可能的 issues 列表，因此如果您在多个仓库中工作，可以包含这些 issues 的查询。查询使用 GitHub 搜索语法。用户列表包括当前打开仓库中的协作者。

Issue Queries

从任何地方创建 issue

当我们正在使用一些源代码时发现 VS Code 中的 bug 时，我们会创建一个 issue 并将其分配给拥有该领域的负责人。或者，如果发现 bug 的人也是负责人，我们通常会留下一个 //TODO 注释作为稍后返回的提醒。在整个代码库中散布的 //TODO 很难跟踪，当您有许多贡献者时（尽管可以肯定的是，我们都做过），但创建 issue 并将其引用在 //TODO 中是可跟踪的。为了降低在深入源代码时创建 issue 的障碍和上下文丢失，这里有几种新的创建 issue 的方法

您可以从 //TODO 注释（可使用 githubIssues.createIssueTriggers 进行配置）创建并分配 issue，而无需离开 VS Code。

Create Issue from TODO

并且从所选内容，您可以使用 GitHub Issues: Create Issue from Selection 命令快速创建一个 issue，并链接回 issue 产生的源代码。如果您只需要指向一些代码，您还可以使用 GitHub Issues: Copy GitHub Permalink 命令。最后，如果终端中有故障信息，您可以将其复制到剪贴板，并使用 GitHub Issues: Create Issue from Clipboard 创建 issue。

处理 Issues

一个常见的流程是查看您的 issues，选择一个要处理的 issue，创建一个分支进行处理，进行一些提交，然后将您的更改合并回 main 分支，并使用 pull request。从新的 Issues 视图中，您可以做到这一点。

Work on an Issue

为了适应更多的流程，您可以配置几个选项。如果您的流程不涉及创建主题分支，可以使用 githubIssues.useBranchForIssues 禁用分支创建。如果您对分支有不同的命名方案，可以使用 githubIssues.issueBranchTitle 设置。Issues 视图中列出的 issues 可以配置为使用自定义查询，方法是使用 githubIssues.queries。

想了解更多信息？

您可以观看 Sana Ajani，GitHub Satellite 的 @sana_ajani 和 Burke Holland，@burkeholland 带来的 每个 GitHub 用户都应该了解的关于 VS Code 的内容 演讲。

您还可以阅读使用 GitHub 主题，其中更详细地介绍了 VS Code 的 GitHub 集成。

未来展望

目前，这些功能中的大部分仅支持仓库克隆（不支持 fork），因此还需要更多的工作来支持这些以及其他用例。我们非常希望收到您对该扩展的反馈，请随时在扩展 repo 中留下建议！

编码愉快！

Alex Ross，VS Code 开发人员 @alexr00