Issues 模板、标签与里程碑

12 minIntermediate

github

Issues 模板配置、Labels、Milestones、自动化关闭关键词与项目板衔接。

1. 背景

Issue（议题） 用于跟踪缺陷、功能请求与讨论。模板（template） 统一报告格式，降低沟通成本；Labels（标签） 分类与筛选；Milestones（里程碑） 聚合版本目标与进度。

2. Issue 模板详解

2.1 模板类型

GitHub 支持多种类型的 Issue 模板：

Bug 报告：用于报告软件缺陷
功能请求：用于提出新功能建议
问题讨论：用于一般性讨论
文档更新：用于文档相关的问题
自定义模板：根据项目需求创建特定模板

2.2 模板配置

2.2.1 文件结构

在仓库根目录创建 .github/ISSUE_TEMPLATE/ 目录，然后添加相应的模板文件：

 .github/
 └── ISSUE_TEMPLATE/
  ├── bug_report.md
  ├── feature_request.md
  ├── question.md
  └── config.yml

2.2.2 YAML 前置元数据

每个模板文件都需要包含 YAML 前置元数据：

- name: 模板名称
  about: 模板用途
  title: "[前缀] 标题"
  labels: 标签1, 标签2
  assignees: 处理人
-

2.2.3 完整模板示例

2.2.3.1 Bug 报告模板

- name: Bug 报告
  about: 报告可复现的缺陷
  title: "[BUG] "
  labels: bug
  templates: bug_report.md
  assignees: ""
-

## 环境

-
-
-

## 复现步骤

1.  打开应用
2.  点击 X 按钮
3.  输入 Y
4.  观察结果

## 期望行为

描述你期望看到的结果

## 实际行为

描述实际发生的情况

## 截图

如果适用，请添加截图来帮助解释问题

## 额外信息

任何其他相关信息

2.2.3.2 功能请求模板

- name: 功能请求
  about: 建议新功能
  title: "[FEATURE] "
  labels: enhancement
  templates: feature_request.md
  assignees: ""
-

## 功能描述

简要描述你希望添加的功能

## 问题背景

解释为什么需要这个功能，它解决了什么问题

## 实现建议

描述你希望如何实现这个功能

## 额外信息

任何其他相关信息

2.3 模板配置文件

使用 config.yml 文件可以自定义 Issue 模板选择界面：

 blank_issues_enabled: false
 contact_links:
  - name: 社区支持
  url: https://github.com/org/repo/discussions
  about: 对于一般问题，请使用讨论区
  - name: 文档
  url: https://docs.example.com
  about: 查看官方文档

3. 标签管理

3.1 标签类型

常见的标签类型包括：

类型标签：bug、enhancement、documentation、question
优先级标签：high-priority、medium-priority、low-priority
状态标签：needs-triage、in-progress、review-needed、fixed
难度标签：good-first-issue、help-wanted、difficult
模块标签：frontend、backend、database、api

3.2 标签最佳实践

命名规范：使用小写字母，单词之间用连字符连接
颜色一致性：为同类标签使用相似的颜色
描述清晰：为每个标签添加描述，说明其用途
数量控制：保持标签数量合理，避免过多标签
团队统一：在组织内统一标签命名和使用规范

3.3 标签管理工具

GitHub 网页界面：在仓库的 Issues 页面管理标签
GitHub CLI：使用 gh label 命令管理标签
GitHub Actions：使用自动化工具自动管理标签

4. 里程碑管理

4.1 里程碑创建

访问仓库的 Issues 页面
点击 Milestones 选项卡
点击 New milestone 按钮
填写里程碑名称、描述和截止日期
点击 Create milestone 按钮

4.2 里程碑使用

关联 Issue：在创建或编辑 Issue 时，选择相应的里程碑
关联 PR：在创建或编辑 PR 时，选择相应的里程碑
跟踪进度：里程碑页面会显示完成百分比
管理截止日期：定期更新里程碑的截止日期

4.3 里程碑最佳实践

命名规范：使用版本号（如 v1.0.0）或迭代名称（如 Sprint 1）
合理范围：每个里程碑包含适量的 Issue，避免过多或过少
明确目标：为每个里程碑设置明确的目标和交付物
定期检查：定期检查里程碑进度，及时调整计划

5. 自动化工具

5.1 GitHub Actions 自动化

5.1.1 自动打标签

 name: Label issues and PRs
 on:
  issues:
  types: [opened, edited]
  pull_request:
  types: [opened, edited]
 jobs:
  label:
  runs-on: ubuntu-latest
  steps:
  - uses: actions/labeler@v5
  with:
  repo-token: "${{ secrets.GITHUB_TOKEN }}"

5.1.2 自动分配 Issue

name: Auto assign issues
on:
  issues:
  types: [opened]
jobs:
  assign:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/assign@v1
  with:
  repo-token: '${{ secrets.GITHUB_TOKEN }}'
  assignees: 'username1, username2'