ljwx-children/docs/best-practices/github-projects-timeline-gantt.md

GitHub Projects 项目进度管理 - 甘特图与时间线

🎯 概述

GitHub Projects V2 提供了强大的项目进度管理功能，包括类似甘特图的时间线视图，可以直观地追踪项目进度、里程碑和依赖关系。

📊 GitHub Projects 的视图类型

1. Table View（表格视图）⭐⭐⭐

最常用的视图，类似电子表格

特点：

• 显示所有字段和数据
• 支持排序、过滤、分组
• 适合详细的数据管理

使用场景：

• 查看和编辑 Issue 详细信息
• 批量更新字段值
• 导出数据

2. Board View（看板视图）⭐⭐⭐

类似 Trello 的看板布局

特点：

• 按字段值分组显示卡片
• 拖拽即可更新状态
• 可视化工作流

使用场景：

• Scrum/Kanban 工作流
• 任务状态追踪
• 团队协作

推荐分组字段：

• Status: Todo → In Progress → Review → Done
• Phase: Requirements → Design → Development → Testing → Deployment
• Document Status: Draft → Review → Approved → Implemented

3. Timeline View（时间线视图 - 甘特图）⭐⭐⭐⭐⭐

最适合项目进度管理

特点：

• 横向时间轴展示
• 显示任务开始和结束日期
• 可视化任务持续时间和重叠
• 支持依赖关系显示

使用场景：

• 项目计划和排期
• 里程碑追踪
• 资源分配
• 进度监控
• 识别瓶颈和延迟

4. Roadmap View（路线图视图）⭐⭐⭐⭐

按季度/月份展示的高层视图

特点：

• 宏观视角
• 按时间段分组
• 适合长期规划

使用场景：

• 产品路线图
• 年度/季度规划
• 高层汇报

🗓️ 配置时间线视图（甘特图）

第一步：添加日期字段

GitHub Projects 需要日期字段来生成时间线视图。

方法 1：使用 GitHub UI

1. 打开项目：https://github.com/orgs/BrunoGaoSZ/projects/2
2. 点击右上角 "⋮" → Settings
3. 点击 "+ New field"
4. 创建以下日期字段：

字段 1: Start Date（开始日期）

Field name: Start Date
Field type: Date
Description: 任务/文档开始日期

字段 2: Target Date（目标日期）

Field name: Target Date
Field type: Date
Description: 计划完成日期

字段 3: Due Date（截止日期）

Field name: Due Date
Field type: Date
Description: 最后期限

方法 2：使用自动化脚本

我将创建一个脚本来自动添加日期字段。

第二步：创建时间线视图

1. 在项目页面，点击当前视图名称旁的 "+" 按钮
2. 选择 "New view"
3. 选择 "Timeline" 作为视图类型
4. 命名为 "Project Timeline" 或 "甘特图"
5. 配置时间线设置：
   • Start date field: Start Date
   • End date field: Target Date
   • Zoom level: Month（按月）/ Week（按周）/ Quarter（按季度）

第三步：配置时间线显示

显示选项：

• Group by: 按 Phase 或 Doc Type 分组
• Color by: 按 Document Priority 着色
• Show markers: 显示今天的标记线
• Show dependencies: 显示依赖关系（如果配置了）

📈 进度追踪最佳实践

1. 日期管理策略

建议使用三个日期字段：

Start Date    ─────────────────────────────────> Target Date ────> Due Date
开始日期         实际工作期间                       计划完成      最后期限
               (在时间线上显示为条形)

日期设置原则：

• Start Date: 任务实际开始日期
• Target Date: 团队预期完成日期（用于甘特图条形结束点）
• Due Date: 硬性截止日期（用于风险预警）

2. 进度字段使用

结合 Progress 数字字段（0-100）：

Progress: 0%     ───────────────────────────>  100%
Status:   Draft  →  Review  →  Approved  →  Implemented

进度更新频率：

• 每日更新（敏捷团队）
• 每周更新（传统项目）
• 里程碑节点更新

3. 里程碑管理

使用 GitHub Milestones：

# 创建里程碑
gh milestone create "Sprint 1" --due-date 2024-01-31 --description "第一个冲刺"
gh milestone create "Alpha Release" --due-date 2024-02-28 --description "Alpha 版本发布"
gh milestone create "Beta Release" --due-date 2024-03-31 --description "Beta 版本发布"

# 将 Issue 关联到里程碑
gh issue edit 1 --milestone "Sprint 1"

里程碑会在时间线视图中显示为垂直标记线

4. 依赖关系管理

使用 Dependencies 文本字段记录依赖：

格式建议：

Dependencies: #1, #2, #5
↑ 表示当前任务依赖 Issue #1, #2, #5 完成

依赖类型：

• Finish-to-Start (FS): 前置任务完成后才能开始（最常见）
• Start-to-Start (SS): 同时开始
• Finish-to-Finish (FF): 同时完成

在时间线上的体现：

• 手动调整开始日期确保依赖关系合理
• 使用 Blocking 字段标注阻塞因素

5. 关键路径识别

手动识别关键路径：

1. 在时间线视图中，按 Phase 分组
2. 找出最长的任务链
3. 使用 Document Priority 标记关键任务为 P0/P1
4. 重点监控关键路径上的任务进度

关键路径任务特征：

• 无缓冲时间（Start Date 到 Due Date 紧凑）
• 被多个任务依赖
• 延期会影响整体项目交付

6. 资源分配可视化

使用 Assignees 字段：

在时间线视图中：

• Group by: Assignees
• Color by: Document Priority

这样可以看到：

• 每个人的任务时间线
• 是否有资源冲突（同一人多个任务重叠）
• 负载是否均衡

🎨 时间线视图配置示例

示例 1：按阶段分组的甘特图

视图名称: SDLC Timeline
视图类型: Timeline
配置:
  - Group by: Phase
  - Color by: Document Priority
  - Start date: Start Date
  - End date: Target Date
  - Zoom: Week
  - Show today marker: Yes

效果：

Phase: Requirements
  ┌─ Issue #1 (BRD) ────────────┐ [P0]
  │  Jan 1 → Jan 15             │
  └──────────────────────────────┘

Phase: Design
      ┌─ Issue #2 (Architecture) ────────┐ [P1]
      │  Jan 16 → Feb 5                   │
      └────────────────────────────────────┘

Phase: Testing
                  ┌─ Issue #3 (Test Cases) ─┐ [P2]
                  │  Feb 6 → Feb 20          │
                  └───────────────────────────┘

示例 2：按人员分组的资源视图

视图名称: Resource Timeline
视图类型: Timeline
配置:
  - Group by: Assignees
  - Color by: Phase
  - Start date: Start Date
  - End date: Target Date
  - Zoom: Week

效果：

Assignee: Alice
  ┌─ Issue #1 ───┐  ┌─ Issue #4 ───┐
  │  Jan 1-15    │  │  Jan 20-31   │
  └──────────────┘  └──────────────┘

Assignee: Bob
       ┌─ Issue #2 ─────────┐  ┌─ Issue #5 ───┐
       │  Jan 10-25         │  │  Feb 1-15    │
       └────────────────────┘  └──────────────┘

🚀 实战指南：为文档管理项目创建甘特图

场景：管理 SDLC 文档开发进度

目标：

• 追踪从 BRD 到部署文档的全流程
• 确保各阶段文档按时完成
• 识别延期风险

步骤 1：规划任务时间线

Issue	文档	Phase	Start	Target	Duration
#1	BRD	Requirements	2024-01-01	2024-01-15	15天
#2	PRD	Requirements	2024-01-10	2024-01-25	16天
#3	架构设计	Design	2024-01-16	2024-02-05	21天
#4	API 文档	Design	2024-01-26	2024-02-10	16天
#5	开发指南	Development	2024-02-06	2024-02-20	15天
#6	测试用例	Testing	2024-02-11	2024-02-25	15天
#7	测试报告	Testing	2024-02-21	2024-03-05	13天
#8	部署文档	Deployment	2024-02-26	2024-03-10	13天

步骤 2：使用 gh CLI 批量设置日期

# 首先需要通过 UI 为每个 Issue 设置日期字段
# 或使用 GraphQL API (见下方脚本)

步骤 3：创建时间线视图

1. 在项目页面创建新视图 "SDLC Document Timeline"
2. 选择 Timeline 类型
3. Group by: Phase
4. Color by: Document Status

步骤 4：监控进度

每周更新：

• 更新 Progress 字段（0-100%）
• 更新 Document Status
• 如有延期，调整 Target Date
• 记录 Blocking 因素

🛠️ 自动化脚本

脚本 1：批量添加日期字段

我将创建 scripts/add-date-fields.py 来自动添加日期字段。

脚本 2：批量设置 Issue 日期

我将创建 scripts/set-issue-dates.py 来批量设置日期。

脚本 3：生成进度报告

我将创建 scripts/generate-progress-report.py 来生成进度报告。

📊 进度报告示例

每周进度报告格式

# SDLC 文档项目进度报告
**报告日期**: 2024-02-15
**报告周期**: Week 7

## 总体进度
- **总任务数**: 8
- **已完成**: 3 (37.5%)
- **进行中**: 2 (25%)
- **未开始**: 3 (37.5%)
- **整体进度**: 42%

## 各阶段状态
| Phase | 任务数 | 完成 | 进行中 | 进度 |
|-------|--------|------|--------|------|
| Requirements | 2 | 2 | 0 | 100% ✅ |
| Design | 2 | 1 | 1 | 75% ⚠️ |
| Development | 1 | 0 | 1 | 30% ⚠️ |
| Testing | 2 | 0 | 0 | 0% |
| Deployment | 1 | 0 | 0 | 0% |

## 延期风险 ⚠️
- **Issue #4 (API 文档)**: 原定 2024-02-10 完成，当前进度 60%，预计延期 5 天
- **Issue #5 (开发指南)**: 阻塞因素：等待架构评审

## 本周完成
- ✅ Issue #1 - BRD (已批准)
- ✅ Issue #2 - PRD (已批准)
- ✅ Issue #3 - 架构设计 (已实施)

## 下周计划
- 完成 Issue #4 - API 文档
- 启动 Issue #6 - 测试用例编写
- 进行架构评审，解除 Issue #5 阻塞

## 关键路径任务
1. Issue #4 → Issue #6 → Issue #7 (测试链路)
2. Issue #5 → Issue #8 (开发到部署链路)

🎯 GitHub Projects 进度管理最佳实践总结

✅ 必做事项

1. 明确时间线

   • 为所有任务设置 Start Date 和 Target Date
   • 设置合理的缓冲时间

2. 定期更新

   • 至少每周更新一次进度
   • 及时调整延期任务的日期

3. 可视化分组

   • 使用多个视图（按阶段、按人员、按状态）
   • 不同场景使用不同视图

4. 标记关键任务

   • 使用 Priority 字段标记关键路径
   • 重点监控 P0/P1 任务

5. 记录依赖和阻塞

   • 明确依赖关系
   • 及时记录阻塞因素

❌ 避免事项

1. 不要过度细化任务（保持在合理粒度）
2. 不要忘记更新进度
3. 不要忽视依赖关系
4. 不要设置不切实际的日期
5. 不要只看一个视图（要多维度分析）

🔗 相关资源

• GitHub Projects 官方文档: https://docs.github.com/en/issues/planning-and-tracking-with-projects
• Timeline View 文档: https://docs.github.com/en/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view
• 项目看板: https://github.com/orgs/BrunoGaoSZ/projects/2

📚 下一步

1. 添加日期字段 - 使用 UI 或脚本
2. 创建时间线视图 - 配置甘特图
3. 设置任务日期 - 为现有 Issues 设置时间线
4. 配置自动化 - 设置进度更新提醒
5. 生成报告 - 定期输出进度报告

---

文档版本: 1.0.0 最后更新: 2024-12-30 维护者: DevOps 团队