Issues 管理

这一课你将能做到

1. 创建一份结构化 Issue（标题、标签、里程碑、负责人、复现步骤）
2. 用标签（Label）与里程碑（Milestone）组织项目需求与缺陷
3. 用「Closes #N」关键词让 PR 合并后自动关闭对应 Issue

为什么要学

Issues 是 GitHub 的「任务管理系统」，任何功能需求、bug 报告、技术讨论都从这里发起。不会用 Issues，团队就不知道你要做什么、优先级是什么、什么时候能上线。好的 Issues 管理能让项目从「混乱的 todo 列表」变成「清晰的作战地图」。

对初学者，Issues 也是参与开源的最佳入口：看到 good first issue 标签的任务，认领下来，就是一次完整的贡献经历。

先建立图像

Issue 的生命周期：

Open（待处理）
   │
   ├─ 被认领，开始开发
   ▼
In Progress（进行中）
   │
   ├─ 开发完成，发 PR
   ▼
Closed（已关闭）
   ├─ 已修复（PR 合并自动关闭）
   ├─ 无法复现
   ├─ 重复问题
   └─ 不会修复（won't fix）

跟着做

步骤 1：创建 Issue

在仓库 Issues 标签页点「New issue」，填写：

**标题**：登录页验证码偶发加载失败

**环境**
- 浏览器：Chrome 120
- 系统：Windows 11

**复现步骤**
1. 访问 https://java-nav.example.com/login
2. 快速连续刷新 5 次
3. 第 3 次开始验证码区域空白

**期望行为**
每次都应正常加载验证码图片

**实际行为**
第 3 次起请求 `/api/captcha` 返回 429，图片不显示

**截图/日志**
[贴浏览器 Network 面板截图]

结构化的 Issue 让开发者不用来回追问。

步骤 2：打标签

创建时右侧栏选 Labels：

• bug：缺陷
• enhancement：功能改进
• documentation：文档
• good first issue：适合新人
• priority:high / priority:medium / priority:low
• status:needs-triage / status:in-progress

步骤 3：指派负责人与里程碑

右侧栏 Assignees 指派给自己或队友，Milestone 关联到版本（如 v1.1.0）。里程碑本质是「一组 Issue 的集合」，用于跟踪版本进度。

步骤 4：开发并关联

git switch -c fix/captcha-429
# 修代码...
git commit -m "fix(captcha): 增加验证码请求限流重试机制"
git push -u origin fix/captcha-429

步骤 5：PR 中关闭 Issue

发 PR 时在描述里写：

Closes #15

PR 合并后，#15 这个 Issue 自动关闭，并显示「由 #PR号 修复」的链接。这是 GitHub 自动化闭环的核心。

步骤 6：用看板管理

仓库 Projects 标签页创建看板，把 Issues 拖进「To do / In progress / Done」三列。这是轻量级项目管理，不用额外装 Jira。

步骤 7：高效搜索与过滤

掌握搜索语法能让你在海量 Issue 中快速定位：

is:issue is:open label:bug                          # 所有未关闭的 bug
is:issue is:open label:"good first issue"           # 适合新人的任务
is:issue assignee:@me                                # 分配给我的
is:issue milestone:v1.1.0                            # 某里程碑下所有任务
is:issue created:>2026-01-01                         # 今年创建的
repo:octocat/Spoon-Knife is:issue is:open            # 跨仓库搜索

配合左侧过滤器（Labels / Milestones / Assignees / Sort），你可以组合出任意视图，例如「按评论数排序的所有未分配高优 bug」。

讲清楚要点

1. Issue 是「对话记录」：描述、评论、决策过程都留在里面，比聊天记录更可追溯。半年后回顾某个功能为什么这样设计，答案就在当时的 Issue 讨论里。
2. 标签是过滤器：搜索 is:issue is:open label:bug label:priority:high 能快速定位所有高优 bug。
3. 里程碑 = 版本目标：把所有计划在 v1.1.0 发布的 Issue 关联到该里程碑，进度条自动计算完成百分比，项目经理一眼看清进度。
4. Closes 关键词：Closes/Fixes/Resolves 后跟 Issue 号，PR 合并时自动关闭。注意只对默认分支（main）有效。
5. @ 提及与任务列表：@username 会通知对方；- [ ] 待办 - [x] 已完成 会在 Issue 列表显示进度条。
6. Issue 模板统一质量：在 .github/ISSUE_TEMPLATE/ 目录放 Markdown 模板（如 bug_report.md、feature_request.md），用户提 Issue 时会自动带出结构化字段，避免「有个 bug」这种无效反馈。

你可能会懵的地方

• Issue 和 PR 有什么区别？ Issue 是「问题/需求」，PR 是「代码改动」。Issue 描述「要做什么」，PR 描述「做了什么」。一个 Issue 可能对应多个 PR，一个 PR 可能关闭多个 Issue。

• Issue 关闭了还能打开吗？ 能，点 Reopen。常见于「以为修好了但用户复现」的情况。

• 为什么我的 PR 合并了 Issue 没自动关？ 检查 PR 描述里的关键词是否写在正文（不能只在标题），以及 Issue 号是否正确。

• 可以一次关多个 Issue 吗？ 可以：Closes #15, closes #16, fixes #17。

• 别人项目的 Issue 我能认领吗？ 看贡献指南（CONTRIBUTING.md）。有些项目要求先评论「I want to work on this」等维护者确认。

错法对照

错法	问题	正解
Issue 标题只写「有个 bug」	无法定位	标题写现象+模块：登录页验证码偶发加载失败
没有复现步骤	开发者无法调试	提供环境、步骤、期望/实际行为
用聊天工具讨论需求，不留 Issue	需求丢失、无法追溯	任何需求先开 Issue
Issue 关闭时没写原因	不知道是真修了还是放弃了	关闭时评论「已修复于 #PR号」或「暂不修复」
里程碑下塞 50 个 Issue	永远完不成	一个里程碑控制在 5-15 个 Issue

卡点急救

1. Issue 写错了想改：右上角 ... → Edit，标题和正文都能改。
2. 想删除 Issue：GitHub 不允许删除（保留历史），只能 Close。误开的测试 Issue 直接 Close 并评论「误开」。
3. 标签不够用：仓库 Settings → Labels 可以新建自定义标签，带颜色区分。

面试常问

• 怎么管理一个项目的 bug 与需求？ 用 Issue + Label + Milestone 三层：Issue 承载具体任务，Label 分类（bug/enhancement/priority），Milestone 按版本分组。看板（Projects）可视化流转状态。

• Issue 和 PR 怎么关联？ PR 描述里用 Closes #N，合并后 Issue 自动关闭；PR 页面右侧「Linked issues」也能手动关联。

• 如何追踪版本发布进度？ 把该版本所有 Issue 关联到对应 Milestone，Milestone 页面自动显示完成百分比和剩余 Issue 列表。

自测三问

1. 为什么 Issue 里要写「期望行为」和「实际行为」？
2. Closes #15 这行魔法写在哪里才生效？
3. 里程碑和标签的区别是什么？

小结一句话

Issues 是项目的作战地图：结构化描述让问题可复现，标签与里程碑让优先级可视化，PR 关联让代码与需求自动闭环。

延伸

• GitHub 文档：使用议题跟踪工作
• 下一课：团队协作——多人并行开发的权限、通知与冲突协调。