介绍 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