ljwx-children/SETUP-FIELDS.md

快速配置 GitHub Project 字段

第一步：获取 GitHub Token

1. 访问：https://github.com/settings/tokens/new
2. 勾选权限：
   • ✅ repo - 仓库访问
   • ✅ project - 项目访问
   • ✅ write:org - 组织项目（如果需要）
3. 点击 "Generate token" 并复制 token

第二步：设置环境变量

export GITHUB_TOKEN="your_token_here"

第三步：预览配置（推荐）

先运行干运行模式，查看会创建哪些字段：

python3 scripts/setup-project-fields.py \
  --project-number 1 \
  --owner @me \
  --dry-run

第四步：应用配置

确认无误后，执行实际配置：

python3 scripts/setup-project-fields.py \
  --project-number 1 \
  --owner @me

将会创建的字段

字段名	类型	选项/说明
Phase	单选	Requirements, Design, Development, Testing, Deployment, Operations
Doc Type	单选	BRD, PRD, Design, API, Test Case, Test Report, Deployment, Operations
Document Priority	单选	P0-Critical, P1-High, P2-Medium, P3-Low
Document Status	单选	Draft, Review, Approved, Implemented, Archived
Progress	数字	0-100 的进度百分比
Blocking	文本	阻塞因素描述
Dependencies	文本	依赖的 Issue 编号

配置后的使用

1. 打开你的项目：https://github.com/users/BrunoGao/projects/1

2. 为 Issue 设置字段值：

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

3. 按字段分组查看：

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

关于字段作用域的说明

✅ 这些字段对你的项目是通用的！

• 字段配置是项目级别的，不是仓库级别的
• 你的项目 #1 可以包含来自不同仓库的 Issues
• 所有添加到项目 #1 的 Issues 都可以使用这些字段
• 例如：

  你的 Project #1 (SDLC Management)
  ├── gold-template/issues/1      ✅ 可以使用所有字段
  ├── gold-template/issues/2      ✅ 可以使用所有字段
  ├── another-repo/issues/5       ✅ 可以使用所有字段
  └── third-repo/issues/10        ✅ 可以使用所有字段
  

❌ 但不会自动在不同项目间共享

• 如果你创建了项目 #2，需要重新配置字段
• 可以使用相同的脚本快速配置
• 或使用配置文件模板保证一致性

故障排除

问题：Token 权限不足

# 检查 token 权限
gh auth status

问题：找不到项目

# 列出所有项目
gh project list --owner @me

# 确认项目编号

问题：字段已存在

脚本会自动跳过已存在的字段，只添加缺失的字段。

更多信息

• 详细文档：docs/best-practices/project-fields-quickstart.md
• 配置说明：docs/best-practices/github-projects-configuration.md
• 配置模板：config/project-fields-template.yml