ljwx-children/docs/best-practices/project-fields-quickstart.md

GitHub Project 字段配置 - 快速入门

🎯 核心结论

GitHub Projects 字段的作用域

✅ 项目级别通用，跨仓库可用

你的 Project (如：SDLC Management)
├── 字段配置（一次性设置）
│   ├── Phase
│   ├── Doc Type
│   ├── Priority
│   └── ...
│
└── 可以包含的 Issues（都可以使用上面的字段）
    ├── gold-template/issues/1      ✅
    ├── gold-template/issues/2      ✅
    ├── another-repo/issues/5       ✅
    └── third-repo/issues/10        ✅

关键点：

• ✅ 在一个项目中配置一次
• ✅ 项目中的所有 Issues 都可以使用
• ✅ 可以添加来自不同仓库的 Issues
• ❌ 字段配置不会自动在不同项目间共享

🚀 三种配置方式

方式 1: GitHub UI 手动配置（推荐新手）⭐

适用场景：

• 首次设置
• 只有 1-2 个项目
• 不需要频繁创建新项目

操作步骤：

1. 打开你的项目

   https://github.com/users/BrunoGao/projects/1
   

2. 进入设置

   • 点击右上角 "⋮" (三个点)
   • 选择 "Settings"

3. 添加字段

   点击 "+ New field" 按钮，添加以下字段：

   字段 1: Phase（阶段）

   Field name: Phase
   Field type: Single select
   Options:
     ☐ Requirements
     ☐ Design
     ☐ Development
     ☐ Testing
     ☐ Deployment
     ☐ Operations
   

   字段 2: Doc Type（文档类型）

   Field name: Doc Type
   Field type: Single select
   Options:
     ☐ BRD
     ☐ PRD
     ☐ Design
     ☐ API
     ☐ Test Case
     ☐ Test Report
     ☐ Deployment
     ☐ Operations
   

   字段 3: Document Priority（优先级）

   Field name: Document Priority
   Field type: Single select
   Options:
     ☐ P0 - Critical
     ☐ P1 - High
     ☐ P2 - Medium
     ☐ P3 - Low
   

   字段 4: Document Status（状态）

   Field name: Document Status
   Field type: Single select
   Options:
     ☐ Draft
     ☐ Review
     ☐ Approved
     ☐ Implemented
     ☐ Archived
   

   字段 5: Progress（进度）

   Field name: Progress
   Field type: Number
   

   字段 6: Dependencies（依赖）

   Field name: Dependencies
   Field type: Text
   

   字段 7: Blocking（阻塞因素）

   Field name: Blocking
   Field type: Text
   

4. 完成！

   • 配置完成后，所有添加到此项目的 Issues 都可以使用这些字段
   • 在项目看板中可以按字段筛选和分组

预计时间： 5-10 分钟

---

方式 2: 使用自动化脚本（推荐团队）⭐⭐⭐

适用场景：

• 需要管理多个项目
• 需要标准化配置
• 团队协作

前提条件：

# 1. 安装 Python 3.8+
python3 --version

# 2. 安装依赖
pip install requests

使用步骤：

1. 获取 GitHub Token

   访问：https://github.com/settings/tokens/new

   权限选择：

   • ✅ repo - 仓库访问
   • ✅ project - 项目访问
   • ✅ write:org - 组织项目（如果需要）

   生成 token 后复制保存

2. 设置环境变量

   export GITHUB_TOKEN="your_github_token_here"
   

3. 运行脚本

   方式 A: 使用项目编号（推荐）

   # 查看你的项目编号
   gh project list --owner @me
   
   # 配置项目字段（项目 #1）
   python scripts/setup-project-fields.py \
     --project-number 1 \
     --owner @me
   

   方式 B: 使用项目 ID

   # 先获取项目 ID
   gh project list --owner @me --format json | jq -r '.[0].id'
   
   # 使用 ID 配置
   python scripts/setup-project-fields.py \
     --project-id PVT_kwHOAgn-Ls4BLjQH
   

4. 预览模式（推荐先试用）

   # 使用 --dry-run 查看会创建哪些字段
   python scripts/setup-project-fields.py \
     --project-number 1 \
     --owner @me \
     --dry-run
   

预计时间： 2-3 分钟

---

方式 3: 配置文件驱动（推荐大规模）⭐⭐

适用场景：

• 多个项目需要相同配置
• 需要自定义字段
• 配置需要版本控制

使用步骤：

1. 创建配置文件

   # 复制模板
   cp config/project-fields-template.yml config/my-project-fields.yml
   
   # 编辑配置
   nano config/my-project-fields.yml
   

2. 自定义字段

   # config/my-project-fields.yml
   fields:
     - name: Phase
       type: SINGLE_SELECT
       options:
         - name: Requirements
           color: BLUE
         # ... 更多选项
   
     # 添加自定义字段
     - name: Estimated Hours
       type: NUMBER
       description: 预估工作小时数
   

3. 应用配置

   # TODO: 扩展脚本支持配置文件
   python scripts/setup-project-fields.py \
     --config config/my-project-fields.yml \
     --project-number 1 \
     --owner @me
   

---

📊 配置完成后的使用

在 Issues 中使用字段

1. 打开项目看板

   https://github.com/users/BrunoGao/projects/1
   

2. 为 Issue 设置字段值

   • 在项目看板中，点击 Issue 卡片
   • 右侧面板会显示所有自定义字段
   • 选择/输入对应的值

3. 按字段筛选和分组

   • 点击看板上方的 "Group by" 按钮
   • 选择字段（如 "Phase"）
   • 看板会自动按阶段分组显示

批量管理

# 查看项目中的所有 Issues
gh project item-list 1 --owner @me --format json

# 添加新 Issue 到项目
gh project item-add 1 --owner @me \
  --url https://github.com/BrunoGaoSZ/gold-template/issues/4

# 在 UI 中设置字段值
# (目前 gh CLI 对字段值设置的支持有限，建议使用 UI)

---

🔄 多项目场景

场景 1: 同一个项目管理多个仓库

不需要重复配置！ ✅

# 创建一个项目
gh project create --owner @me --title "All My Projects"

# 配置字段（只需一次）
python scripts/setup-project-fields.py --project-number 1 --owner @me

# 添加来自不同仓库的 Issues
gh project item-add 1 --owner @me --url https://github.com/user/repo1/issues/1
gh project item-add 1 --owner @me --url https://github.com/user/repo2/issues/5
gh project item-add 1 --owner @me --url https://github.com/user/repo3/issues/10

# 所有 Issues 都可以使用相同的字段！

场景 2: 为不同产品创建独立项目

每个项目需要单独配置 ⚠️

# 产品 A 的项目
gh project create --owner @me --title "Product A"
python scripts/setup-project-fields.py --project-number 1 --owner @me

# 产品 B 的项目
gh project create --owner @me --title "Product B"
python scripts/setup-project-fields.py --project-number 2 --owner @me

# 使用配置文件可以快速复制相同配置

场景 3: 创建项目模板

创建一个"模板项目" 💡

# 1. 创建并配置模板项目
gh project create --owner @me --title "Template - SDLC Management"
python scripts/setup-project-fields.py --project-number 1 --owner @me

# 2. 为新项目复用配置（使用脚本）
# 创建新项目
gh project create --owner @me --title "New Project"

# 复用相同的字段配置
python scripts/setup-project-fields.py --project-number 2 --owner @me

# 3. 文档化你的标准配置
# 保存 config/project-fields-template.yml
# 提交到 git，团队成员都可以使用

---

❓ 常见问题

Q1: 我已经手动配置了，还能用脚本吗？

A: 可以！脚本会：

• ✅ 跳过已存在的字段
• ✅ 只添加缺失的字段
• ✅ 不会修改现有字段

# 安全运行，不会重复创建
python scripts/setup-project-fields.py --project-number 1 --owner @me

Q2: 字段配置会影响到其他项目吗？

A: 不会！

• ❌ 字段配置是项目级别的
• ✅ 每个项目的配置独立
• ✅ 不会相互影响

Q3: 可以修改已创建的字段吗？

A: 可以，但有限制：

• ✅ 可以添加/删除选项（单选字段）
• ✅ 可以重命名字段
• ⚠️ 修改字段类型可能丢失数据
• 💡 建议在 GitHub UI 中修改

Q4: 如何删除不需要的字段？

A: 在 GitHub UI 中删除：

1. 打开 Project Settings
2. 找到要删除的字段
3. 点击 "⋮" → "Delete field"

Q5: 脚本执行失败怎么办？

A: 常见问题排查：

# 1. 检查 Token 权限
gh auth status

# 2. 验证 Token 是否设置
echo $GITHUB_TOKEN

# 3. 使用 dry-run 模式测试
python scripts/setup-project-fields.py \
  --project-number 1 --owner @me --dry-run

# 4. 查看详细错误信息
python scripts/setup-project-fields.py \
  --project-number 1 --owner @me --verbose

---

📝 推荐工作流

首次设置（推荐流程）

# 1. 手动配置（体验功能）
#    在 GitHub UI 中为项目添加 2-3 个字段
#    体验字段的使用方式

# 2. 使用脚本完善（自动化）
export GITHUB_TOKEN="your_token"
python scripts/setup-project-fields.py --project-number 1 --owner @me

# 3. 验证结果
#    在 GitHub UI 中查看所有字段是否正确

# 4. 开始使用
#    为 Issues 设置字段值
#    按字段分组查看

团队协作（推荐流程）

# 1. 保存标准配置到代码仓库
git add config/project-fields-template.yml
git commit -m "Add standard project fields configuration"

# 2. 团队成员克隆配置
git pull

# 3. 创建各自的项目
gh project create --owner @me --title "My Project"

# 4. 应用标准配置
python scripts/setup-project-fields.py --project-number 1 --owner @me

# 5. 整个团队使用统一的字段配置！

---

🎉 总结

方式	难度	时间	适用场景
GitHub UI 手动	⭐ 简单	5-10分钟	1-2个项目，首次使用
Python 脚本	⭐⭐ 中等	2-3分钟	多个项目，团队协作
配置文件	⭐⭐⭐ 复杂	首次需要编写	大规模，需要定制

最佳实践：

1. 首次使用：先用 UI 配置 1-2 个字段体验
2. 团队使用：使用脚本标准化配置
3. 大规模使用：使用配置文件管理

立即开始：

# 最简单的方式
python scripts/setup-project-fields.py --project-number 1 --owner @me

# 预览模式（推荐先试用）
python scripts/setup-project-fields.py --project-number 1 --owner @me --dry-run

---

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