引入 GitHub Issues 集成

Name: Visual Studio Code
Author: Microsoft

2020 年 5 月 6 日，作者 Alex Ross，@alexr00

在 Visual Studio Code 团队中，我们使用 GitHub issues 来跟踪所有工作。从详细的迭代计划到单个 bug，我们都将一切跟踪为 GitHub issue。考虑到 issues 对我们的团队和其他 GitHub 项目的重要性，我们希望在 VS Code 中添加 GitHub issues 集成。这一新增功能补充了我们一年多前宣布的 GitHub 拉取请求工作。从 VS Code 1.45 版本开始，这项新的支持将 issue 和源代码更紧密地联系起来，该支持将在 GitHub Pull Requests and Issues 扩展（以前称为 GitHub Pull Requests）中提供。

我们的集成方法

Issues 和拉取请求常常是相辅相成的，因此将它们包含在同一个 GitHub Pull Requests and Issues 扩展中是合乎逻辑的一步，因为 issues 和拉取请求都需要大量的相同 GitHub API。我们不希望直接将 GitHub 功能添加到 VS Code 核心编辑器中，因为有许多源代码控制选项。相反，当检测到用户打开的仓库使用 GitHub 时，我们将推荐该扩展。通过使用我们自己的扩展 API，我们确保 API 具有扩展作者所需的功能，并且其他仓库提供商可以实现类似的集成。

重要的是我们不应规定过于具体的工作流程。相反，我们的目标是以灵活的方式将 issue 引入到内部开发循环中。例如，在代码注释中为 issue 提供更多上下文是这一目标的一部分，但将完整的 issue 管理添加到 VS Code 中就不太合适了。我们不想重新发明 GitHub 已经做得很好的 UI。我们确实想建立一些尚不存在的连接。

代码上下文中的 Issues

在源代码中链接到 issue 是我们工作流程的正常部分，尤其是在存在一些难以理解的逻辑或存在需要采取行动的 //TODO 注释时。如果您在 VS Code 仓库中搜索 issue 引用，您会看到提到许多 issue。虽然链接提供了更多信息的指针，但要真正了解更多信息，您需要离开编辑器。现在，通过悬停获取 issue 上下文，您无需中断流程即可了解更多信息。

Issue Hover

Issue 悬停适用于完整的 issue URL、issue 评论 URL、按编号引用的 issue（#1234）以及按 owner/repository#1234 引用的 issue（例如 Microsoft/vscode#1234）。我们还经常在代码库中引用用户。VS Code 的提案 API 有许多开发者引用，以便清楚地说明谁负责这些提案。

User Hover

在提交消息中通常需要 Issue 上下文来引用提交解决的 issue、在源代码文件内以及在 Markdown 中（例如更新日志）。为了轻松添加此上下文，我们为 issue 和用户添加了完成建议。在 Git 提交文本框中，您可以使用 githubIssues.issueCompletionFormatScm 设置格式化您的 issue 完成。在 Markdown 文件中，issue 以 Markdown 链接的形式完成，在其他文件中，issue 以简单的 issue 编号（#1234）的形式完成。

Completion Suggestions

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

Issue Queries

从任何地方创建 issue

当我们在处理某些源代码时在 VS Code 中发现 bug 时，我们会创建一个 issue 并将其分配给该区域的负责人。或者，如果发现 bug 的人也是负责人，我们通常会留下 //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

一个常见的工作流程是查看您的 issue，选择一个进行处理，创建一个分支进行工作，进行一些提交，然后通过拉取请求将您的更改合并回 main 分支。您可以在新的Issues视图中完成这项工作。

Work on an Issue

为了适应更多工作流程，您可以配置多个选项。如果您的流程不涉及创建主题分支，可以使用 githubIssues.useBranchForIssues 禁用分支创建。如果您的分支命名方案不同，可以使用 githubIssues.issueBranchTitle 设置。可以在Issues视图中配置 issue 列表以使用自定义查询，通过 githubIssues.queries 设置。

想了解更多？

您可以观看 Sana Ajani @sana_ajani 和 Burke Holland @burkeholland 在 GitHub Satellite 上关于每个 GitHub 用户都应该了解的 VS Code 知识的演讲。

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

未来展望

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

编程愉快！

Alex Ross，VS Code 开发者 @alexr00