本文主要介绍了开源项目中管理 GitHub Issue 规范的相关内容。

简介

对 git 项目来讲，问题追踪是很重要的。在整个 GitHub，谁都可以提问 issue，谁都可以对 issue 问题进行回答。但如果没有适当的处理，项目会变得很庞大，挤满重复的 bug issue、模糊不明的 feature request。

Git Issue

每个 Github 代码仓库都有一个 Issues 面板，进入该面板：

点击 New Issue 按钮，就可以新建 Issue：

新建 Issue 的界面，左侧填入 Issue 的标题和内容，右侧是四个配置项（只有项目管理者才能看到）:

1. Assignees：人员
2. Labels：标签
3. Due Data：截止日期
4. Milestone：里程碑

Assignee

Assignee（指派人）是被指定为负责解决或处理特定 issue 的个人或团队。当一个 issue 被指派给某人后，该人会收到通知，并负责跟踪和解决该问题。

通常情况下，issue 的创建者或项目维护者会根据任务的性质和相关人员的专业知识来选择指派人。一般来说，Assignee 应该是能够解决该问题或任务的人员。

Labels

GitHub 中的 Labels 是用于对 issue 进行分类和标记的标签系统。通过给 issue 添加标签，可以更好地组织和管理项目中的问题、功能请求和任务。

如果想新建更多的标签，可以点击 New label 按钮。然后，填写标签名，选择标签颜色。

类型

一般来说，Labels 可以分为几种常见类型：

1. 类型标签：表示 issue 的类型，如 bug、feature、enhancement 等。
2. 优先级标签：表示 issue 的优先级，如 high priority、medium priority、low priority 等。
3. 状态标签：表示 issue 的状态，如 open、closed、in progress、pending review 等。
4. 模块标签：表示 issue 所属的模块或子系统，有助于快速定位问题的范围。
5. 其他标签：根据项目的需要，还可以添加其他类型的标签，如 difficulty、help wanted、documentation 等。

示例

以下是几个在 GitHub 上常用的标签示例：

1. Bug（缺陷）：用于标识报告的问题是软件中的 bug。通常用红色或者醒目的颜色表示。这个标签可以帮助团队快速识别和解决软件中存在的问题。
2. Feature（功能）：用于标识关于新增功能或特性的请求。通常用绿色或者类似的醒目颜色表示。这个标签可以帮助团队管理和追踪项目中新功能的开发和实现。
3. Enhancement（增强）：类似于 Feature 标签，用于标识对现有功能的改进或增强请求。通常用黄色或者类似的颜色表示。这个标签可以帮助团队管理和追踪项目中现有功能的改进和优化。
4. Documentation（文档）：用于标识与项目文档相关的问题或任务。通常用蓝色或者类似的颜色表示。这个标签可以帮助团队管理和追踪项目文档的编写、更新和维护。
5. Help Wanted（寻求帮助）：用于标识需要额外帮助或贡献的问题或任务。通常用绿色或者类似的颜色表示。这个标签可以吸引更多的贡献者参与到项目中，提供帮助和支持。
6. Duplicate（重复）：用于标识当前 issue 是一个已经存在的重复问题。通常用灰色或者类似的颜色表示。这个标签可以帮助团队避免重复处理相同的问题，提高工作效率。
7. Invalid（无效）：用于标识当前 issue 是无效或者不相关的。通常用灰色或者类似的颜色表示。这个标签可以帮助团队快速识别并关闭无效的问题，保持 issue 列表的整洁。

这些是一些常用的 GitHub 标签示例，当然具体使用时，你可以根据项目的特点和需求定义自己的标签，并为其选择合适的颜色和描述。

Milestone

GitHub 中的 Milestone（里程碑）是一种用于将一组相关的 issue 或 pull request 分组到特定版本、阶段或目标中的功能。通过为一组相关的任务或功能设置里程碑，可以更好地组织和管理项目的开发进度。

在 GitHub 上，项目管理员或具有相应权限的用户可以创建里程碑。创建里程碑时，需要指定里程碑的标题、描述、截止日期等信息。

一旦创建了里程碑，你可以将与特定版本、阶段或目标相关的一组 issue 或 pull request 分配给该里程碑。这样，你可以将相关的任务集中在一起，并在开发过程中跟踪其进度。

里程碑页面会显示与该里程碑相关的所有 issue 和 pull request，以及它们的状态、进度和更新。这使得团队可以更方便地跟踪任务的完成情况，并了解项目的开发进度。

新建 Milestone，要在 Issues 面板的首页，点击 Milestones 按钮。这时，再接着点击 New milestone 按钮，然后填写 Milestone 的名称和内容，还可以指定到期时间。如下图所示：

在很多的项目中，我们通常都可以看到，在项目的根目录上面存放有 .github 这样的文件，它常用于存储项目的 GitHub 配置文件和模板。这些文件可以用于管理项目的工作流程、自动化任务和规范代码贡献。

以下是 .github 文件夹中可能包含的一些常见文件和目的：

1. ISSUE_TEMPLATE：该文件夹包含用于创建 issue 的模板文件。通过提供预定义的模板，可以帮助用户更清晰地描述问题、功能请求或反馈，并确保必要的信息被提供。
2. PULL_REQUEST_TEMPLATE：该文件夹包含用于创建 pull request 的模板文件。通过提供预定义的模板，可以帮助贡献者描述其提交的更改内容、解决的问题以及测试方法等信息。
3. CODEOWNERS：该文件指定了代码贡献者和代码审查者的所有者。GitHub 根据这个文件中的配置来确定哪些人或团队对于特定文件或目录的更改有审查权和责任。
4. workflows：该文件夹包含 GitHub Actions 的工作流配置文件。GitHub Actions 是一种用于自动化项目工作流程的工具，可以通过配置工作流文件来定义和执行各种自动化任务，如测试、构建、部署等。
5. CONTRIBUTING：该文件包含了贡献指南，提供了关于如何贡献代码、提交问题和参与社区讨论的说明和规范。
6. SECURITY：该文件夹包含了与项目安全相关的文件，如安全策略、漏洞报告指南等。这些文件帮助项目团队和用户了解如何报告安全漏洞和问题，并提供安全建议和最佳实践。

那么接下来我们将来学习一下怎么新创 Iss 模板，让你的项目变得规范起来。

首先我们在 .github 目录下创建一个 ISSUE_TEMPLATE 目录，在这里我们可以创建一个 yaml 文件和 md 文件都可以，在这里我们就采用 yaml 的方式来进行演示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

name: "Discussion"
description: Start a discussion
title: "[Discuss]: Discussion Title"
labels: [discussion]
assignees: []
body:
  - type: textarea
    id: topic
    attributes:
      label: Discussion Topic
      description: "Please provide a clear and concise topic for discussion."
    validations:
      required: true
  - type: textarea
    id: screenshots
    attributes:
      label: Screenshots
      description: "If applicable, add screenshots to help explain your topic."
  - type: textarea
    id: links
    attributes:
      label: Links
      description: "Include any relevant links that could provide more context for the discussion."

name 是名称，这是用于描述该 issue 的目的或者主题，而 description 是对主题的简要描述，用于解释该板块的用途或目的。在这里，描述是 “Start a discussion”，表示该板块用于开始讨论。

title 是用于创建新讨论时的默认标题格式。在这里，标题格式是 “[Discuss]: Discussion Title”，这意味着每个新讨论的标题将以 “[Discuss]” 开头，后跟具体的讨论标题。

labels 是为新讨论指定的标签。在这里，标签是一个名为 “discussion” 的标签，它可能用于标识讨论类别或主题。例如，你可以使用不同的标签来表示不同类型的讨论话题，比如问题、建议、反馈等。

assignees: 这是将要被指定为讨论负责人的 GitHub 用户列表。

body 是讨论模板的主体部分，用于指定讨论时需要填写的字段和内容。

通过这种方式我们就可以创建到了一些 issue 模板了，最终我们整个项目的 issue 模板应该是这样的：

使用 YAML 文件创建 GitHub issue 模板可以规范化和简化用户创建 issue 的流程，提高 issue 内容的质量和可读性，从而增加团队的工作效率。

参考资料

• https://juejin.cn/post/7344325496983781402

文章链接：
https://www.zywvvd.com/notes/tools/git/git-issue-stan/git-issue-stan/