GitHub Projects 项目管理¶

GitHub Projects 是 GitHub 内置的项目管理工具，直接关联代码仓库中的 Issue 和 PR，用表格、看板、时间线视图管理开发任务，2025 年大升级支持子任务和 Issue 类型，对开发者来说比 Jira 更顺手。

核心知识点¶

知识点	说明
工具定位	GitHub 内置的项目管理工具
核心优势	与 Issue/PR 深度集成、免费、开发者友好
2025 更新	Sub-issues、Issue Types、高级搜索、5 万条目
视图类型	Table / Board / Roadmap
定价	免费（GitHub 账号即可使用）
竞品	Jira、Linear、Asana

安装配置¶

=== 无需安装，GitHub 内置 ===

1. 登录 github.com
2. 个人主页或组织主页 → Projects 标签
3. New Project → 选择模板
4. 开始使用

=== 模板选择 ===
- Board: 看板视图（Kanban 风格）
- Table: 表格视图（类似电子表格）
- Roadmap: 时间线视图（甘特图风格）
- Team backlog: 团队待办（预设字段）
- Bug tracker: Bug 追踪（预设标签）

基本使用¶

1. 创建和管理项目¶

=== 创建 Project ===

github.com → 你的头像 → Your projects → New project

=== 添加条目 ===
方式 1: 在 Project 中直接添加
  - 点击底部 "+ Add item"
  - 输入标题 → Enter
  - 自动创建 Draft（草稿条目）

方式 2: 从 Issue 添加
  - 在 Issue 页面右侧 → Projects → 选择项目
  - Issue 自动出现在 Project 中

方式 3: 从 PR 添加
  - 在 PR 页面右侧 → Projects → 选择项目
  - PR 状态自动与 Project 同步

方式 4: 批量添加
  - 在 Project 中 → + → Add items from repository
  - 搜索并批量添加 Issue

2. 视图类型¶

=== Table 视图（表格）===
类似电子表格，每行一个任务：
| Title | Status | Assignee | Priority | Sprint |
|-------|--------|----------|----------|--------|
| 质控流程 | Done | @user1 | High | Sprint 1 |
| 物种注释 | In Progress | @user2 | Medium | Sprint 1 |

=== Board 视图（看板）===
按 Status 分列显示：
┌──Todo──┐ ┌──In Progress──┐ ┌──Done──┐
│ Task 3 │ │ Task 2       │ │ Task 1│
│ Task 4 │ │              │ │       │
└────────┘ └──────────────┘ └───────┘
拖拽卡片即可改变状态

=== Roadmap 视图（时间线）===
甘特图风格，显示任务时间跨度：
|-- Task 1 --|
     |--- Task 2 ---|
          |-- Task 3 --|
需要设置 Start date 和 End date 字段

3. 自定义字段¶

=== 添加字段 ===
点击表头 "+" → 新建字段

=== 字段类型 ===
Text           文本
Number         数字
Date           日期
Single select  单选（如 Status: Todo/Doing/Done）
Iteration      迭代周期（Sprint）
Tracks / Tracked by  父子关系追踪

=== 推荐字段配置 ===
Status:     Todo / In Progress / In Review / Done
Priority:   🔴 High / 🟡 Medium / 🟢 Low
Sprint:     Sprint 1 / Sprint 2 / Sprint 3
Size:       XS / S / M / L / XL（工作量）
Start date: 开始日期
End date:   截止日期

4. Issue 基础操作¶

=== 创建 Issue ===

在仓库中：Issues → New issue
或用 GitHub CLI:

gh issue create --title "实现丰度可视化" \
  --body "## 需求\n柱状图展示物种丰度\n## 验收标准\n- 支持排序\n- 支持导出" \
  --label "feature" \
  --assignee "@me" \
  --project "宏基因组分析"

=== Issue 模板 ===
在仓库中创建 .github/ISSUE_TEMPLATE/ 目录：

# .github/ISSUE_TEMPLATE/bug_report.md
---
name: Bug 报告
about: 报告一个 Bug
labels: bug
---

## 描述
[描述 Bug]

## 复现步骤
1. 
2. 
3. 

## 期望行为
[应该发生什么]

## 实际行为
[实际发生了什么]

## 环境
- OS: 
- Python: 
- 相关包版本:

高级用法¶

1. Sub-issues（子任务，2025 新功能）¶

=== 子任务 ===

现在 Issue 可以有子 Issue：
1. 打开一个 Issue
2. 在描述中添加子任务列表
3. 或在 Issue 页面点 "Add sub-issue"

示例：
# 宏基因组分析流程 v2
- [ ] #12 质控模块
  - [ ] #13 fastp 集成
  - [ ] #14 MultiQC 报告
- [ ] #15 比对模块
  - [ ] #16 BWA-MEM2 集成
  - [ ] #17 Minimap2 支持
- [ ] #18 物种注释

=== 进度追踪 ===
父 Issue 自动显示子任务完成进度条
例: ████░░░░ 4/8 (50%)

2. Issue Types（2025 新功能）¶

=== Issue 类型 ===

组织级别的 Issue 分类系统：
- Bug           缺陷报告
- Feature       功能请求
- Task          任务
- Epic          大的功能模块
- Spike         技术调研

=== 使用 ===
在仓库 Settings → Issue Types 中配置
创建 Issue 时选择类型
在 Project 中按类型筛选和分组

3. 自动化（Workflows）¶

=== 内置自动化 ===

Project Settings → Workflows

预设规则：
- Item added to project → 设置 Status = "Todo"
- Issue closed → 设置 Status = "Done"
- PR merged → 设置 Status = "Done"
- Code review requested → 设置 Status = "In Review"

=== 自定义自动化（GitHub Actions）===

# .github/workflows/project-automation.yml
name: Auto-add to Project
on:
  issues:
    types: [opened]                    # Issue 被创建时

jobs:
  add-to-project:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/add-to-project@v1
        with:
          project-url: https://github.com/orgs/ORG/projects/1
          github-token: ${{ secrets.GITHUB_TOKEN }}

4. GitHub CLI 操作¶

# 用 gh 命令行管理项目

# 查看项目
gh project list                        # 列出所有项目
gh project view 1                      # 查看项目详情

# 创建 Issue
gh issue create -t "Bug: 质控失败" -l "bug" -a "@me"

# 列出 Issue
gh issue list                          # 所有 Issue
gh issue list --label "bug"            # 按标签筛选
gh issue list --assignee "@me"         # 我的 Issue

# 关闭 Issue
gh issue close 123                     # 关闭 Issue #123

# PR 操作
gh pr create -t "修复质控Bug" -b "修复了 fastp 参数问题"
gh pr list                             # 列出 PR
gh pr merge 456                        # 合并 PR #456

# 在 Issue 和 PR 中关联
# PR 描述中写: "Fixes #123" → 合并后自动关闭 Issue #123
# "Closes #123" / "Resolves #123" 也可以

5. 高级搜索（2025 新功能）¶

=== 高级搜索语法 ===

在 Project 搜索框中使用：

# AND 组合
status:"In Progress" AND assignee:@me

# OR 选择
label:bug OR label:critical

# 嵌套括号
(label:bug OR label:feature) AND priority:high

# 排除
NOT status:Done

# 示例：查找我的高优先级未完成任务
assignee:@me AND priority:high AND NOT status:Done

常见报错与解决¶

报错信息	原因	解决方法
无法添加 Issue	权限不足	需要仓库 write 权限
字段不显示	视图未配置	点击表头 "+" 添加字段
自动化不触发	Workflow 未开启	Project Settings → Workflows
条目数限制	超过上限	2025 后已扩展到 5 万条

速查表¶

===== GitHub Projects 速查表 =====

# 核心概念
Project = 项目看板
Issue   = 任务/Bug/功能请求
PR      = 代码变更请求
Draft   = 草稿条目（不关联仓库）

# 视图
Table     表格视图（类似 Excel）
Board     看板视图（Kanban）
Roadmap   时间线视图（甘特图）

# 推荐字段
Status:    Todo / In Progress / Done
Priority:  High / Medium / Low
Sprint:    迭代周期
Assignee:  负责人
Labels:    标签

# CLI 命令
gh issue create -t "标题"      创建 Issue
gh issue list                  列出 Issue
gh issue close 123             关闭 Issue
gh pr create                   创建 PR
gh pr merge 456                合并 PR
gh project list                列出项目

# Issue 关联 PR
PR 描述中写: "Fixes #123"
→ PR 合并后自动关闭 Issue #123

# 2025 新功能
Sub-issues   子任务（嵌套 Issue）
Issue Types  Issue 分类（Bug/Feature/Task）
高级搜索     AND/OR/NOT/括号
5 万条目     上限大幅提升

# GitHub Projects vs Jira
# GitHub Projects: 免费、与代码深度集成、简单
# Jira: 功能最全、配置最多、企业标准
# 建议：代码为中心的项目用 GitHub Projects