引入 GitHub Issues 集成

Name: Visual Studio Code
Author: Microsoft

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

在 Visual Studio Code 团队中，我们使用 GitHub issues 来跟踪我们所有的工作。从我们详细的迭代计划到单个错误，我们都将一切作为 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 和拉取请求通常是并行的，因此将它们包含在同一个 GitHub Pull Requests and Issues 扩展中是合乎逻辑的一步，因为 issues 和拉取请求都需要许多相同的 GitHub API。我们不想将 GitHub 功能直接添加到核心 VS Code 编辑器中，因为有许多源代码控制选项。相反，当我们检测到用户的打开存储库使用 GitHub 时，我们将推荐该扩展。通过使用我们自己的扩展 API，我们确保 API 具有扩展作者所需的功能，并且其他存储库提供商可以实现类似的集成。

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

代码上下文中的 Issues

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

Issue Hover

Issue 悬停适用于完整的 issue URL、issue 注释 URL、通过编号 (#1234) 引用的 issue，以及通过 owner/repository#1234 (例如 Microsoft/vscode#1234) 引用的 issue。我们还经常在代码库中引用用户。VS Code 提议的 API 有许多开发人员引用，以便明确谁负责这些提议。

User Hover

Issue 上下文通常在提交消息中需要，以引用提交解决的 issue，以及在源代码文件和 Markdown 中（例如变更日志）。为了轻松添加此上下文，我们为 issue 和用户添加了完成建议。在 Git 提交文本框中，您可以使用 githubIssues.issueCompletionFormatScm 设置格式化您的 issue 完成。在 Markdown 文件中，issues 作为 Markdown 链接完成；在其他文件中，issues 作为简单的 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: 从选中内容创建 Issue”命令快速创建一个 issue，并带有指向原始源代码的永久链接。如果您只需要指向某些代码的指针，您还可以使用“GitHub Issues: 复制 GitHub 永久链接”命令。最后，如果终端中有失败信息，您可以直接将输出复制到剪贴板，然后使用“GitHub Issues: 从剪贴板创建 Issue”创建 issue。

处理 Issues

常见的工作流程是查看您的 issue、选择一个进行处理、创建分支进行工作、进行一些提交，然后通过拉取请求将更改合并回主分支。从新的“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” (What every GitHub user should know about VS Code)。

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

未来展望

目前，这些功能大多仅支持存储库克隆（而非 fork），因此还需要做更多工作来支持这一点以及其他用例。我们很乐意看到您对这个扩展的反馈，所以请随时在扩展的存储库中的 issue 中给我们留下建议！

编码愉快！

Alex Ross，VS Code 开发人员 @alexr00