GitHub问题、标签和里程碑

GitHub 问题（issues）可以帮助你跟踪任务、增强功能和 bug。它们具有高度的协作性，并且有一个显示其历史的时间线。问题可以与提交、拉取请求和其他问题关联。GitHub 问题是开发人员在 GitHub 上喜爱的体验的一部分。这也是为什么它们是管理工程团队工作的一种良好解决方案。

创建新问题

你可以在你的仓库中通过 “Issues | New Issue” 创建一个新问题。问题有一个标题和一个支持 Markdown 的正文（见图 2.4）：

Figure 1. 图 2.4 – 创建新问题

工具栏可以帮助你格式化文本。除了常见的格式设置——如标题、粗体和斜体文本、列表、链接和图片，它还具有一些值得注意的功能：

表情符号：你可以在 Markdown 中添加各种表情符号。我的一些最爱是 :+1: (👍)、:100: (💯) 和 GitHub 特有的 :shipit: 松鼠。你可以在这里找到完整的列表： https://gist.github.com/rxaviers/7360908#file-gistfile1-md。
提及：你可以通过 GitHub 句柄提及个别成员，或提及整个团队。只需按 @ 并开始输入，选择列表中的人或团队。他们会收到通知，且提及将显示为链接，指向该人员或团队的个人资料。
引用：按 # 键并选择列表中的项目，可以引用其他问题、拉取请求或讨论。
任务列表：任务列表是显示问题进度的子任务列表。任务可以转换为问题，从而用于创建嵌套的工作项层级。未完成的任务前缀是 - [ ]，已完成的任务前缀是 - [x]。
源代码：你可以将带有语法高亮的源代码添加到 Markdown 中。只需使用 ``` 来打开和关闭代码块。语法高亮由 linguist（ https://github.com/github/linguist ）完成，支持大多数语言。

Markdown 是一种非常流行的轻量级标记语言。与 JSON 或 HTML 不同，Markdown 基于单行格式化文本，不需要开启和关闭的标签或括号。这使得它非常适合使用 Git 进行版本控制，并通过拉取请求协作修改。这也是为什么 YAML 成为机器可读文件的事实标准，而 Markdown 则成为人类可读文件的等效格式的原因。在 DevOps 团队中，一切都是代码：图表、架构、设计和概念文档、配置文件以及基础设施。因此，Markdown 或 YAML，或两者的混合被广泛使用。

如果你还没有学习 Markdown，现在是时候开始了。许多团队在拉取请求中广泛使用 Markdown 来协作编辑人类可读内容。由于大多数工作管理解决方案也支持 Markdown，它几乎无处不在。

Markdown 的语法非常简单，容易学习。使用几次后，它应该不会成为负担。

你可以随时切换到预览模式，以查看 Markdown 的输出（见图 2.5）：

Figure 2. 图 2.5 – 在新问题中预览 Markdown

在 GitHub 上有一个很好的 Markdown 入门教程，你可以在这里找到： https://guides.github.com/features/mastering-markdown/ 。

如果你经常使用相似的文本块，可以保存回复。按 Ctrl + .（Windows/Linux）或 Cmd + .（Mac），从列表中选择回复，或者创建一个新的保存回复。想了解更多信息，请参见： https://docs.github.com/en/github/writing-on-github/working-with-savedreplies 。

协作处理问题

一旦问题被创建，你可以随时添加评论。你可以最多为该问题分配 10 个人，并为其应用标签以进行分类。所有的变更都会显示为该问题历史中的事件（见图 2.6）：

Figure 3. 图 2.6 – 编辑问题

如果你的问题包含任务列表，它将用于显示问题的进度。你可以将每个任务转换为一个独立的问题，并将其链接到当前的问题。如果你点击 “打开转换为问题” 按钮（请注意图 2.6 中的鼠标悬停效果），该任务将被转换为一个新问题，并显示为一个链接。如果你点击该链接并打开问题，你可以看到该问题被追踪在另一个问题中（见图 2.7）：

Figure 4. 图 2.7 – 创建问题的层次结构

通过这种方式，你可以创建灵活的工作层次结构，并将工作拆分为更小的任务。

问题积压

问题概览并不是真正的待办事项列表，因为它不能通过拖放轻松排序。但它具有非常先进的筛选和排序语法。你应用的每个筛选条件都会作为文本添加到搜索字段中（见图 2.8）：

Figure 5. 图 2.8 – 筛选和排序问题列表

在概览中，你可以看到任务的进度和标签。你还可以看到与问题相关联的拉取请求。

里程碑

里程碑是分组问题的一种方式。一个问题只能被分配到一个里程碑。里程碑通过已关闭问题与总问题数的比例来衡量进度。里程碑有一个标题、一个可选的截止日期和一个可选的描述（见图 2.9）：

Figure 6. 图 2.9 – 使用里程碑规划问题

里程碑是分组问题的好方法，适用于具有特定目标日期的发布版本。它们也可以用于将不属于发布版本的所有问题一起分组。

置顶问题

您可以将最多三个问题置顶到您的仓库。这些问题将显示在问题概览的顶部（见图 2.10）：

Figure 7. 图 2.10 – 固定问题

置顶问题是与其他贡献者或新团队成员沟通重要事项的好方法。

问题模板

您可以为问题配置不同的模板，这些模板提供了预定义的内容。如果用户创建新问题，他们可以从列表中选择模板（见图 2.11）：

Figure 8. 图 2.11 – 问题模板

您可以在仓库的设置中启用问题模板，路径为 Settings | Options | Issues | Set up templates。您可以选择一个基本模板，用于报告错误、功能请求或自定义模板。这些模板是存储在仓库中的文件，位于 .github/ISSUE_TEMPLATE 目录下。点击 Propose changes 并将文件提交到您的仓库。一旦模板文件进入仓库，您可以直接在仓库中编辑或删除它们，或者添加新的模板文件。无需通过设置来添加新模板文件。

模板可以是 Markdown (.md) 或 YAML 文件 (.yml)。Markdown 模板包含一个头部，指定模板的名称和描述。它还可以为标题、标签和指派人设置默认值。以下是一个 Markdown 模板的示例：

---
name: 🐞 Bug report
about: Create a report to help us improve
title: ‘[Bug]:’
labels: [bug, unplanned]
assignees:
- wulfland
---

**Describe the bug**
A clear and concise description of what the bug is.

**To Reproduce**
...

如果您点击 Issues | New Issue，您可以选择模板并点击 Get started。新建的问题将会填充模板中的值。结果如图 2.12 所示：

Figure 9. 图 2.12 – 一个 Markdown 问题模板

使用 YAML 模板，您可以定义包含文本框、下拉框和复选框的完整表单。您可以配置控件并将字段标记为必填。一个示例表单可以这样定义：

name: 💡 Custom Issue Form
description: A custom form with different fields
body:
  - type: input
    id: contact
    attributes:
      label: Contact Details
      description: How can we get in touch with you if we need more info?
      placeholder: ex. email@example.com
    validations:
      required: false
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: Also tell us, what did you expect to happen?
      placeholder: Tell us what you see!
      value: “Tell us what you think”
    validations:
      required: true
  - type: dropdown
    id: version
    attributes:
      label: Version
      description: What version of our software are you running?
      options:
        - 1.0.2 (Default)
        - 1.0.3 (Edge)
    validations:
      required: true
  - type: dropdown
    id: browsers
    attributes:
      label: What browsers are you seeing the problem on?
      multiple: true
      options:
        - Firefox
        - Chrome
        - Safari
        - Microsoft Edge
  - type: checkboxes
    id: terms
    attributes:
      label: Code of Conduct
      description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
      options:
        - label: I agree to follow this project’s Code of Conduct
          required: true

结果如图 2.13 所示：

Figure 10. 图 2.13 – YAML 问题模板

你可以在这里找到有关 YAML 问题模板的更多信息： https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms 。

你可以通过将 config.yml 文件添加到 .github/ISSUE_TEMPLATE 来自定义选择问题模板的对话框。你可以设置是否支持空白问题，并添加额外的行：

blank_issues_enabled: true
contact_links:
  - name: 👥 Discussions
    url: https://github.com/wulfland/AccelerateDevOps/discussions/new
    about: Please use discussions for issues that are not a bug, enhancement or feature request

结果如图 2.11 所示，额外的链接显示为一个 Open 按钮。

在撰写本书时，YAML 问题模板仍处于 beta 阶段，因此可能会发生变化。