nofx/docs/maintainers/SETUP_GUIDE.zh-CN.md

🚀 PR 管理系统设置指南

语言： English | 中文

本指南将帮助你为 NOFX 设置和激活完整的 PR 管理系统。

---

📦 包含内容

PR 管理系统包括：

1. 文档

• ✅ CONTRIBUTING.md - 贡献者指南
• ✅ docs/maintainers/PR_REVIEW_GUIDE.md - 审核者指南
• ✅ docs/maintainers/PROJECT_MANAGEMENT.md - 项目管理工作流程
• ✅ docs/maintainers/SETUP_GUIDE.md - 本文件

2. GitHub 配置

• ✅ .github/PULL_REQUEST_TEMPLATE.md - PR 模板（已存在）
• ✅ .github/labels.yml - 标签定义
• ✅ .github/labeler.yml - 自动标签规则
• ✅ .github/workflows/pr-checks.yml - 自动化 PR 检查

3. 自动化

• ✅ 自动 PR 标签
• ✅ PR 大小检查
• ✅ CI/CD 测试
• ✅ 安全扫描
• ✅ Commit 信息验证

---

🔧 设置步骤

步骤 1：同步 GitHub 标签

创建 .github/labels.yml 中定义的标签：

# 选项 1：使用 gh CLI（推荐）
gh label list  # 查看当前标签
gh label delete <label-name>  # 如需要，删除旧标签
gh label create "priority: critical" --color "d73a4a" --description "Critical priority"
# ... 为 labels.yml 中的所有标签重复

# 选项 2：使用 GitHub Labeler Action（自动化）
# 工作流将在推送时自动同步标签

或使用 GitHub Labeler Action（添加到 .github/workflows/sync-labels.yml）：

name: Sync Labels
on:
  push:
    branches: [main, dev]
    paths:
      - '.github/labels.yml'

jobs:
  labels:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: crazy-max/ghaction-github-labeler@v5
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          yaml-file: .github/labels.yml

步骤 2：启用 GitHub Actions

1. 前往 Settings → Actions → General
2. 启用 "Allow all actions and reusable workflows"
3. 设置 Workflow permissions 为 "Read and write permissions"
4. 勾选 "Allow GitHub Actions to create and approve pull requests"

步骤 3：设置分支保护规则

对于 main 分支：

1. 前往 Settings → Branches → Add rule
2. 分支名称模式：main
3. 配置：
   • ✅ Require a pull request before merging
   • ✅ Require approvals: 1
   • ✅ Require status checks to pass before merging
     • 选择：Backend Tests (Go)
     • 选择：Frontend Tests (React/TypeScript)
     • 选择：Security Scan
   • ✅ Require conversation resolution before merging
   • ✅ Do not allow bypassing the above settings
   • ❌ Allow force pushes（禁用）
   • ❌ Allow deletions（禁用）

对于 dev 分支：

1. 与上面相同，但：
   • Require approvals: 1
   • 宽松一些（如需要允许维护者绕过）

步骤 4：创建 GitHub Projects

1. 前往 Projects → New project

2. 创建 "NOFX Development" 看板

   • 模板：Board
   • 添加列：Backlog、Triaged、In Progress、In Review、Done
   • 添加视图：Sprint、Roadmap、By Area、Priority

3. 创建 "Bounty Program" 看板

   • 模板：Board
   • 添加列：Available、Claimed、In Progress、Under Review、Paid

步骤 5：启用 Discussions（可选但推荐）

1. 前往 Settings → General → Features
2. 启用 "Discussions"
3. 创建分类：
   • 💬 General - 一般讨论
   • 💡 Ideas - 功能想法和建议
   • 🙏 Q&A - 问答
   • 📢 Announcements - 重要更新
   • 🗳️ Polls - 社区投票

步骤 6：配置 Issue 模板

模板已存在于 .github/ISSUE_TEMPLATE/ 中。验证它们是否正常工作：

1. 前往 Issues → New issue
2. 你应该看到：
   • 🐛 Bug Report
   • ✨ Feature Request
   • 💰 Bounty Claim

如果没有显示，检查文件是否为正确格式的 YAML 和 frontmatter。

步骤 7：设置 Code Owners（可选）

创建 .github/CODEOWNERS：

# 全局所有者
* @tinkle @zack

# 前端
/web/ @frontend-lead

# 交易所集成
/internal/exchange/ @exchange-lead

# AI 组件
/internal/ai/ @ai-lead

# 文档
/docs/ @tinkle @zack
*.md @tinkle @zack

步骤 8：配置通知

对于维护者：

1. 前往 Settings → Notifications

2. 启用：

   • ✅ Pull request reviews
   • ✅ Pull request pushes
   • ✅ Comments on issues and PRs
   • ✅ New issues
   • ✅ Security alerts

3. 设置电子邮件过滤器来组织通知

对于仓库：

1. 前往 Settings → Webhooks（如果与 Slack/Discord 集成）
2. 添加通知 webhook

---

📋 设置后检查清单

设置后，验证：

• 标签已创建并可见
• 分支保护规则已激活
• GitHub Actions 工作流在新 PR 上运行
• 自动标签工作（创建测试 PR）
• 创建 PR 时显示 PR 模板
• 创建 issue 时显示 issue 模板
• Projects 看板可访问
• CONTRIBUTING.md 在 README 中链接

---

🎯 如何使用系统

对于贡献者

1. 阅读 CONTRIBUTING.md
2. 查看 路线图了解优先级
3. 开启 issue 或找到现有的
4. 使用模板创建 PR
5. 处理审核反馈
6. 庆祝 当合并时！🎉

对于维护者

1. 每日： 分类新 issue/PR（15分钟）
2. 每日： 审查分配的 PR
3. 每周： Sprint 计划（周一）和回顾（周五）
4. 遵循： PR 审核指南
5. 遵循： 项目管理指南

对于悬赏猎人

1. 查看 带有 bounty 标签的悬赏 issue
2. 通过评论认领 issue
3. 在截止日期前完成
4. 提交 PR 并填写悬赏认领部分
5. 合并后获得报酬

---

🔍 测试系统

测试 1：创建测试 PR

# 创建测试分支
git checkout -b test/pr-system-check

# 进行小改动
echo "# Test" >> TEST.md

# 提交并推送
git add TEST.md
git commit -m "test: verify PR automation system"
git push origin test/pr-system-check

# 在 GitHub 上创建 PR
# 验证：
# - PR 模板加载
# - 应用了自动标签
# - CI 检查运行
# - 添加了大小标签

测试 2：创建测试 Issue

1. 前往 Issues → New issue
2. 选择 Bug Report
3. 填写模板
4. 提交
5. 验证：
   • 模板正确渲染
   • Issue 可以被标签
   • Issue 出现在项目看板中

测试 3：测试自动标签

创建改动不同区域文件的 PR：

# 测试 1：前端变更
git checkout -b test/frontend-label
touch web/src/test.tsx
git add . && git commit -m "test: frontend labeling"
git push origin test/frontend-label
# 应该得到 "area: frontend" 标签

# 测试 2：后端变更
git checkout -b test/backend-label
touch internal/test.go
git add . && git commit -m "test: backend labeling"
git push origin test/backend-label
# 应该得到 "area: backend" 标签

---

🐛 故障排除

问题：标签未同步

解决方案：

# 首先删除所有现有标签
gh label list --json name --jq '.[].name' | xargs -I {} gh label delete "{}" --yes

# 然后从 labels.yml 手动创建或通过 action 创建

问题：GitHub Actions 未运行

检查：

1. 仓库设置中启用了 Actions
2. 工作流文件在 .github/workflows/ 中
3. YAML 语法有效
4. 权限设置正确

调试：

# 本地验证工作流
act pull_request  # 使用 'act' 工具

问题：分支保护阻止 PR

检查：

1. 必需的检查在工作流中定义
2. 检查名称完全匹配
3. 检查正在完成（没有卡住）

临时修复：

• 维护者可以在紧急情况下绕过
• 如果太严格，调整保护规则

问题：自动标签器不工作

检查：

1. .github/labeler.yml 存在且为有效 YAML
2. labeler.yml 中定义的标签在仓库中存在
3. 工作流有 pull-requests: write 权限

---

📊 监控和维护

每周回顾

每周检查这些指标：

# 使用 gh CLI
gh pr list --state all --json number,createdAt,closedAt
gh issue list --state all --json number,createdAt,closedAt

# 或使用 GitHub Insights
# Repository → Insights → Pulse, Contributors, Traffic

每月维护

• 如需要审查和更新标签
• 检查工作流中的过期依赖
• 如果流程变更更新 CONTRIBUTING.md
• 审查自动化效果
• 收集社区反馈

---

🎓 培训资源

对于新贡献者

• 首次贡献指南
• 如何写 Git Commit 信息
• Conventional Commits

对于维护者

• 代码审核的艺术
• GitHub 项目管理
• 维护者社区

---

🎉 一切就绪！

PR 管理系统现在已准备好：

✅ 用清晰的指南引导贡献者 ✅ 自动化重复任务 ✅ 保持代码质量 ✅ 系统性地跟踪进度 ✅ 扩展社区

有问题？ 在维护者频道联系我们或开启讨论。

让我们构建令人惊叹的社区！🚀