软件项目开发全流程 · 第 14 课 · 协作平台：GitHub 上的项目管理

1、代码托管 ≠ 项目管理

第 12、13 课我们把 Git 和分支策略讲透了。但一个真实的团队项目，仓库里跑的不只是代码，还有一堆"管理问题"：

「这个 Bug 谁认领了？修到哪一步了？」
「下个版本到底要做什么？做完了吗？」
「这个需求当时为什么这么定？谁拍的板？」

这些如果靠聊天群和脑子记，很快就是一团乱麻：消息刷屏、责任不清、进度靠猜。

协作平台（Collaboration Platform）的价值，就是把「代码 + 任务 + 讨论 + 进度」放进同一个地方，并且互相能追溯。

GitHub / GitLab / Gitee 不只是「代码网盘」。它们真正的核心是：让「要做什么、正在做什么、做到哪了、为什么这么做」四件事彼此可查。

2、一个仓库里的"四件套"

以 GitHub 为例，一个健康项目的协作对象通常有四类：

Repository（仓库）
 ├── Code       代码 + 分支 + PR          （第 12、13 课）
 ├── Issues     问题 / 任务 / 想法         ← 本课重点
 ├── Projects   看板 / 表格 / 路线图        ← 本课重点
 └── Docs/Wiki  文档与知识沉淀             （第 18 课）

它们的关系可以用一句话记住：

Issue 描述「要做什么」，PR 表示「正在做」，Projects 展示「做到哪了」，文档沉淀「为什么这么做」。

把这四样都用起来，你就不再靠"群里喊一声"来管理项目了。

3、Issue：最小的工作单元

Issue（议题）是 GitHub 上最小的工作单元。它可以是：

一个 Bug（"登录后偶尔白屏"）
一个任务（"给搜索加拼音支持"）
一个 改进想法（"把导出的 CSV 换成 xlsx"）
一个 问题讨论（"我们该用 Postgres 还是 MySQL？"）

一个好 Issue 和一段好代码一样，讲究结构：

### 现象 / 目标
登录页在弱网下点击"提交"后偶尔白屏，刷新后正常。

### 复现步骤
1. 打开登录页
2. 手机切换到 3G 网络
3. 快速点击"提交"两次

### 期望
重复点击只提交一次，或给出加载中反馈。

### 环境
Chrome 126 / Windows 11 / v2.3.1

为什么值得花时间写清楚？ 因为 Issue 是异步协作的基础——你不必把所有人拉到一个群里同步解释一遍。写清楚一次，所有人随时能看懂。

Issue 模板：把"写清楚"变成默认

在仓库里放 .github/ISSUE_TEMPLATE/，新建 Issue 时就会自动套用模板（Bug 模板、功能模板……）。用模板约束格式，比靠人自觉可靠得多（和第 16 课"让机器管风格"是同一个思路）。

4、标签体系（Labels）：给 Issue 分类

Issue 一多，就得能筛。标签是分类的抓手。不要随便建一堆标签，而是成体系地设计：

维度	示例标签	用途
类型	`bug` `feature` `docs` `question`	这是什么
优先级	`P0` `P1` `P2`	多急（呼应第 5 课优先级）
状态	`triage` `in-progress` `blocked`	到哪一步了
难度/规模	`good first issue` `size:S/M/L`	好不好上手、多大
协作	`help wanted`	欢迎大家来认领

设计原则：

每个维度建一组，别把"类型"和"优先级"混在一起说。
标签宁少勿滥。20 个以内基本够用，太多就没人贴了。
good first issue 是给新人留的门——它让外部贡献者和新同事有明确的切入点。

5、Milestone 与 Projects：看进度，而不靠问

Milestone（里程碑）

Milestone 是一组 Issue 的集合，对应一个明确的交付目标——"v1.0 上线要做的所有事"。它和第 5 课的里程碑概念完全一致，只是落到了工具里。

给 Issue 挂上 Milestone，GitHub 会自动算完成百分比：

milestone: v1.0 上线
  ████████░░░░░░░░  8 / 15 done (53%)

Projects：看板 / 表格 / 路线图

Projects 是可视化面板，同一批 Issue 可以用三种视角看：

看板（Board）      表格（Table）       路线图（Roadmap）
┌────┬────┬────┐   ┌──────┬─────┬───┐   Q1      Q2
│Todo│Doing│Done│   │标题  │负责 │状态│   ├──v1.0
├────┼────┼────┤   ├──────┼─────┼───┤        ├──v1.1
│ #12│ #8 │ #3 │   │ #12  │ 小李│Todo│
└────┴────┴────┘   └──────┴─────┴───┘

这正对应第 17 课的敏捷看板：Todo / Doing / Done 三列，就是最朴素的待办 / 进行中 / 完成。

Projects 最省心的用法是"自动化"：

一个 Issue 被指派（assigned）→ 自动移到 Doing
关联的 PR 被合并 → 自动移到 Done
Issue 被关闭 → 自动移出看板

让状态跟着事实走，人就不用天天手动拖卡片。

6、联动：让代码和任务互相"咬合"

GitHub 最香的地方，是代码、PR、Issue 自动关联。你只需要在提交信息或 PR 描述里写关键词 + Issue 号：

feat: 支持拼音搜索

Closes #128

支持的关闭关键词：close / closes / fix / fixes / resolve / resolves（大小写不敏感）。

一旦这个 PR 被合并，Issue #128 会全自动关闭，并在两边留下互相的链接。带来的好处：

可追溯：从任意一个 Issue 能跳到改动它的 PR，从 PR 能跳回需求。
不留尾巴：不会出现"PR 合了但 Issue 忘关"的僵尸任务。
可用 Fixes #…：直接表达"这个提交修复了那个缺陷"（呼应第 22 课 Bug 生命周期）。

这就是第 7 课"需求追溯矩阵"在协作平台上的免费实现：需求（Issue）↔ 设计（讨论）↔ 代码（PR）↔ 验证（测试），一条链全在仓库里。

7、权限与分支保护：把规矩"焊死"

协作平台也是规则落地的地方（和第 13 课呼应）：

角色与权限：read / triage / write / maintain / admin，按最小权限授予。
分支保护：main 禁止直接 push，必须走 PR（第 13 课）。
Code Owners：CODEOWNERS 文件声明"哪些目录归谁审"，提 PR 时自动 @ 到对应负责人。
PR 模板：.github/PULL_REQUEST_TEMPLATE.md，让大家提交 PR 时不忘写"改了什么、怎么测的"。

核心思想：能用平台配置强制的规矩，就不要靠口头约定。 人会忘，配置文件不会。

8、常见坑

坑	后果	应对
用聊天群当任务系统	消息被刷掉，任务丢失	一切任务进 Issue，群里只贴链接
Issue 不写复现步骤/验收标准	反复来回问，效率低	用模板约束，参照第 7 课写 AC
标签五花八门	没人愿意贴，筛选失效	先定 3~4 个维度，总数控制在 20 内
看板全靠手动拖	卡片状态永远落后于现实	打开 Projects 自动化规则
PR 描述只有一句"修了个 bug"	无法追溯、评审困难	用 PR 模板，写清动机与验证方式
Issue 久拖不决、无人认领	积压成山，士气低落	定期 triage，设 `stale` 自动提醒

9、动手实验 🎯

任务：给你的项目搭一套好用的 GitHub 项目管理。

建 3 个 Issue 模板：Bug、功能、任务（放 .github/ISSUE_TEMPLATE/）。
设计一套标签体系：至少覆盖「类型 / 优先级 / 状态」三个维度，每个 Issue 贴好标签。
建一个 Milestone（比如 v1.0），把本阶段要做的 Issue 都挂上去，观察自动完成的百分比。
建一个 Projects 看板，设为 Todo / Doing / Done，并打开自动化规则（指派→Doing，合并→Done）。
开一个 PR，描述里写 Closes #<某个 Issue 号>，合并后确认 Issue 自动关闭。
加一个 CODEOWNERS 文件和 PR 模板，验证提 PR 时自动请求对应负责人评审。
写一段 200 字的团队协作约定：什么进 Issue、模板怎么用、看板怎么维护。

做完这步，你的项目就有了"中枢神经"——任务、进度、代码、讨论全在一个地方可查。下一课进入持续集成（CI），让这些提交每次都被自动验证。

10、今天你带走的三句话

协作平台的核心是"可追溯"：Issue 说清要做什么、PR 表示正在做、Projects 展示做到哪、文档沉淀为什么。
写清楚比说清楚更值钱：用 Issue/PR 模板约束格式，用标签体系给任务分类，异步协作才跑得动。
让状态跟着事实走：Closes #123 自动关单、看板自动流转、分支保护强制评审——能用配置强制的，就别靠人记。

下一课讲持续集成（CI）——把"每次提交都自动构建 + 自动测试"变成团队的肌肉记忆。