liuyu/nofx
1
0
Fork 0
mirror of https://github.com/NoFxAiOS/nofx.git synced 2026-06-06 05:51:19 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: pr validation

Browse Source
This commit is contained in:
zbhan
2025-11-01 18:25:44 -04:00
parent c7a6b64a9a
commit 2f4f277001
22 changed files with 6607 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

398
docs/maintainers/PROJECT_MANAGEMENT.md Normal file
View File

@@ -0,0 +1,398 @@
# 📊 Project Management Guide
**Language:** [English](PROJECT_MANAGEMENT.md) | [中文](PROJECT_MANAGEMENT.zh-CN.md)
This guide explains how we manage the NOFX project, track progress, and prioritize work.
---
## 🎯 Project Structure
### GitHub Projects
We use **GitHub Projects (Beta)** with these boards:
#### 1. **NOFX Development Board**
**Columns:**
```
Backlog → Triaged → In Progress → In Review → Done
```
**Views:**
- 📋 **All Issues** - Kanban view of all work items
- 🏃 **Sprint** - Current sprint items (2-week sprints)
- 🗺️ **Roadmap** - Timeline view by roadmap phase
- 🏷️ **By Area** - Grouped by area labels
- 🔥 **Priority** - Sorted by priority (critical/high/medium/low)
- 👥 **By Assignee** - Grouped by assigned maintainer
#### 2. **Bounty Program Board**
**Columns:**
```
Available → Claimed → In Progress → Under Review → Paid
```
---
## 📅 Sprint Planning (Bi-weekly)
### Sprint Schedule
**Sprint Duration:** 2 weeks
**Sprint Planning:** Every other Monday
**Sprint Review:** Every other Friday
### Planning Process
**Monday - Sprint Planning (1 hour):**
1. **Review previous sprint** (15 min)
- What was completed?
- What was not completed and why?
- Metrics review
2. **Prioritize backlog** (20 min)
- Review new issues/PRs
- Update priorities based on roadmap
- Assign labels
3. **Plan next sprint** (25 min)
- Select items for next sprint
- Assign to maintainers
- Set clear acceptance criteria
- Estimate effort (S/M/L)
**Friday - Sprint Review (30 min):**
1. **Demo completed work** (15 min)
- Show merged PRs
- Demonstrate new features
2. **Retrospective** (15 min)
- What went well?
- What can improve?
- Action items for next sprint
---
## 🏷️ Issue Triage Process
### Daily Triage (Mon-Fri, 15 min)
Review new issues and PRs:
1. **Verify completeness**
- Template filled properly?
- Reproduction steps clear (for bugs)?
- Use case explained (for features)?
2. **Apply labels**
```yaml
Priority:
- priority: critical # Security, data loss, production down
- priority: high # Major bugs, high-value features
- priority: medium # Regular bugs, standard features
- priority: low # Nice-to-have, minor improvements
Type:
- type: bug
- type: feature
- type: enhancement
- type: documentation
- type: security
Area:
- area: exchange
- area: ai
- area: frontend
- area: backend
- area: security
- area: ui/ux
Roadmap:
- roadmap: phase-1 # Core Infrastructure
- roadmap: phase-2 # Testing & Stability
- roadmap: phase-3 # Universal Markets
```
3. **Assign or tag for discussion**
- Can handle immediately? Assign to maintainer
- Needs discussion? Tag for next planning session
- Needs more info? Request from author
4. **Close if needed**
- Duplicate? Close with link to original
- Invalid? Close with explanation
- Out of scope? Close politely with reasoning
---
## 🎯 Priority Decision Matrix
Use this matrix to decide priority:
| Impact / Urgency | High Urgency | Medium Urgency | Low Urgency |
|------------------|--------------|----------------|-------------|
| **High Impact** | 🔴 Critical | 🔴 Critical | 🟡 High |
| **Medium Impact** | 🔴 Critical | 🟡 High | 🟢 Medium |
| **Low Impact** | 🟡 High | 🟢 Medium | ⚪ Low |
**Impact:**
- High: Affects core functionality, security, or many users
- Medium: Affects specific features or moderate users
- Low: Nice-to-have, minor improvements
**Urgency:**
- High: Needs immediate attention
- Medium: Should be addressed soon
- Low: Can wait for natural inclusion
---
## 📊 Roadmap Alignment
All work should align with our [roadmap](../roadmap/README.md):
### Phase 1: Core Infrastructure (Current Focus)
**Must Accept:**
- Security enhancements
- AI model integrations
- Exchange integrations (OKX, Bybit, Lighter, EdgeX)
- Project structure refactoring
- UI/UX improvements
**Can Accept:**
- Related bug fixes
- Documentation improvements
- Performance optimizations
**Should Defer:**
- Universal market expansion (stocks, futures)
- Advanced AI features (RL, multi-agent)
- Enterprise features
### Phase 2-5: Future Work
Mark with appropriate `roadmap: phase-X` label and add to backlog.
---
## 🎫 Issue Templates
We have these issue templates:
### 1. Bug Report
- Use for bugs and errors
- Must include reproduction steps
- Label: `type: bug`
### 2. Feature Request
- Use for new features
- Must include use case and benefits
- Label: `type: feature`
### 3. Bounty Claim
- Use when claiming a bounty
- Must reference bounty issue
- Label: `bounty: claimed`
### 4. Security Vulnerability
- Use for security issues (private)
- Follow responsible disclosure
- Label: `type: security`
**Missing a template?**
- Use blank issue
- Maintainers will convert to appropriate template
---
## 📈 Metrics We Track
### Weekly Metrics
- **PR Metrics:**
- Number of PRs opened
- Number of PRs merged
- Average time to first review
- Average time to merge
- **Issue Metrics:**
- Number of issues opened
- Number of issues closed
- Issue backlog size
- Issues by priority/type/area
- **Community Metrics:**
- New contributors
- Active contributors
- Community engagement (comments, reactions)
### Monthly Metrics
- **Roadmap Progress:**
- % completion per phase
- Items completed vs planned
- Blockers and risks
- **Code Quality:**
- Test coverage
- Code review comments per PR
- Bug fix vs feature ratio
- **Bounty Program:**
- Bounties created
- Bounties claimed
- Bounties paid
- Average completion time
---
## 🤖 Automation
We use GitHub Actions for automation:
### PR Automation
- **Automatic labeling** based on files changed
- **PR size labeling** (small/medium/large)
- **CI checks** (tests, linting, build)
- **Security scans** (Trivy, Gitleaks)
- **Conventional commit validation**
### Issue Automation
- **Stale issue detection** (closes after 30 days inactive)
- **Automatic bounty labeling** when "bounty" keyword used
- **Duplicate detection** using issue similarity
### Release Automation
- **Changelog generation** from conventional commits
- **Version bumping** based on commit types
- **Release notes** auto-generated
- **Deployment** to staging/production
---
## 🔄 Regular Tasks
### Daily
- ✅ Triage new issues/PRs
- ✅ Review urgent PRs
- ✅ Respond to community questions
### Weekly
- ✅ Sprint planning (Monday)
- ✅ Sprint review (Friday)
- ✅ Review metrics dashboard
- ✅ Update project boards
### Monthly
- ✅ Roadmap progress review
- ✅ Community update post
- ✅ Bounty program review
- ✅ Dependency updates
- ✅ Security audit
### Quarterly
- ✅ Roadmap update
- ✅ Major release planning
- ✅ Contributor recognition
- ✅ Documentation audit
---
## 📞 Communication Channels
### Internal (Maintainers)
- **GitHub Discussions:** Architecture decisions, RFC
- **Private channel:** Sensitive discussions, bounty payments
- **Weekly sync:** Sprint planning and review
### External (Community)
- **Telegram:** [@nofx_dev_community](https://t.me/nofx_dev_community)
- **GitHub Issues:** Bug reports, feature requests
- **GitHub Discussions:** General questions, ideas
- **Twitter:** [@nofx_ai](https://x.com/nofx_ai) - Announcements
---
## 🎓 Onboarding New Maintainers
### Checklist for New Maintainers
- [ ] Add to GitHub organization
- [ ] Grant write access to repository
- [ ] Add to private maintainer channel
- [ ] Introduce to the team
- [ ] Read all docs in `/docs/maintainers/`
- [ ] Shadow experienced maintainer for 1 sprint
- [ ] First solo PR review (with backup reviewer)
- [ ] First solo issue triage
- [ ] First sprint planning participation
### Expectations
**Time Commitment:**
- ~5-10 hours per week
- Participate in sprint planning/review
- Respond to assigned issues/PRs within SLA
**Responsibilities:**
- Code review
- Issue triage
- Community support
- Documentation maintenance
---
## 🏆 Contributor Recognition
### Monthly Recognition
**Spotlight in Community Update:**
- Top contributor
- Best PR of the month
- Most helpful community member
### Quarterly Recognition
**Contributor Tier System:**
- 🥇 **Core Contributor** - 20+ merged PRs
- 🥈 **Active Contributor** - 10+ merged PRs
- 🥉 **Contributor** - 5+ merged PRs
- ⭐ **First Timer** - 1+ merged PR
**Benefits:**
- Recognition in README
- Invitation to private Discord
- Early access to features
- Swag (for Core Contributors)
---
## 📚 Resources
### Internal Docs
- [PR Review Guide](PR_REVIEW_GUIDE.md)
- [Security Policy](../../SECURITY.md)
- [Code of Conduct](../../CODE_OF_CONDUCT.md)
### External Resources
- [GitHub Project Management](https://docs.github.com/en/issues/planning-and-tracking-with-projects)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Semantic Versioning](https://semver.org/)
---
## 🤔 Questions?
Reach out in the maintainer channel or open a discussion.
**Let's build something amazing together! 🚀**

398
docs/maintainers/PROJECT_MANAGEMENT.zh-CN.md Normal file
View File

@@ -0,0 +1,398 @@
# 📊 项目管理指南
**语言：** [English](PROJECT_MANAGEMENT.md) | [中文](PROJECT_MANAGEMENT.zh-CN.md)
本指南解释了我们如何管理 NOFX 项目、跟踪进度和优先级排序。
---
## 🎯 项目结构
### GitHub Projects
我们使用 **GitHub Projects (Beta)** 和以下看板：
#### 1. **NOFX 开发看板**
**列：**
```
Backlog → Triaged → In Progress → In Review → Done
```
**视图：**
- 📋 **所有 Issue** - 所有工作项的看板视图
- 🏃 **Sprint** - 当前 Sprint 项（2 周 Sprint）
- 🗺️ **路线图** - 按路线图阶段的时间轴视图
- 🏷️ **按区域** - 按区域标签分组
- 🔥 **优先级** - 按优先级排序（critical/high/medium/low）
- 👥 **按分配人** - 按分配的维护者分组
#### 2. **悬赏计划看板**
**列：**
```
Available → Claimed → In Progress → Under Review → Paid
```
---
## 📅 Sprint 计划（双周）
### Sprint 时间表
**Sprint 周期：** 2 周
**Sprint 计划：** 每隔一周的星期一
**Sprint 回顾：** 每隔一周的星期五
### 计划流程
**星期一 - Sprint 计划（1小时）：**
1. **回顾上一个 Sprint**（15分钟）
- 完成了什么？
- 什么没有完成？为什么？
- 指标回顾
2. **优先级排序 Backlog**（20分钟）
- 审查新的 issue/PR
- 基于路线图更新优先级
- 分配标签
3. **计划下一个 Sprint**（25分钟）
- 选择下一个 Sprint 的项目
- 分配给维护者
- 设定清晰的验收标准
- 估算工作量（S/M/L）
**星期五 - Sprint 回顾（30分钟）：**
1. **演示已完成的工作**（15分钟）
- 展示已合并的 PR
- 演示新功能
2. **复盘**（15分钟）
- 什么做得好？
- 什么可以改进？
- 下一个 Sprint 的行动项
---
## 🏷️ Issue 分类流程
### 每日分类（周一至周五，15分钟）
审查新的 issue 和 PR：
1. **验证完整性**
- 模板是否正确填写？
- 重现步骤清晰吗（对于 bug）？
- 使用场景解释清楚吗（对于功能）？
2. **应用标签**
```yaml
优先级：
- priority: critical # 安全问题、数据丢失、生产环境宕机
- priority: high # 主要 bug、高价值功能
- priority: medium # 常规 bug、标准功能
- priority: low # 可选功能、次要改进
类型：
- type: bug
- type: feature
- type: enhancement
- type: documentation
- type: security
区域：
- area: exchange
- area: ai
- area: frontend
- area: backend
- area: security
- area: ui/ux
路线图：
- roadmap: phase-1 # 核心基础设施
- roadmap: phase-2 # 测试与稳定性
- roadmap: phase-3 # 通用市场
```
3. **分配或标记讨论**
- 可以立即处理？分配给维护者
- 需要讨论？标记在下次计划会议
- 需要更多信息？从作者处请求
4. **必要时关闭**
- 重复？关闭并链接到原始 issue
- 无效？关闭并说明原因
- 超出范围？礼貌关闭并说明理由
---
## 🎯 优先级决策矩阵
使用此矩阵决定优先级：
| 影响/紧急程度 | 高紧急 | 中等紧急 | 低紧急 |
|------------------|--------------|----------------|-------------|
| **高影响** | 🔴 Critical | 🔴 Critical | 🟡 High |
| **中等影响** | 🔴 Critical | 🟡 High | 🟢 Medium |
| **低影响** | 🟡 High | 🟢 Medium | ⚪ Low |
**影响：**
- 高：影响核心功能、安全性或许多用户
- 中：影响特定功能或中等数量用户
- 低：可选功能、次要改进
**紧急程度：**
- 高：需要立即关注
- 中：应该尽快处理
- 低：可以等待自然包含
---
## 📊 路线图对齐
所有工作应与我们的[路线图](../roadmap/README.zh-CN.md)对齐：
### Phase 1：核心基础设施（当前重点）
**必须接受：**
- 安全增强
- AI 模型集成
- 交易所集成（OKX、Bybit、Lighter、EdgeX）
- 项目结构重构
- UI/UX 改进
**可以接受：**
- 相关 bug 修复
- 文档改进
- 性能优化
**应该推迟：**
- 通用市场扩展（股票、期货）
- 高级 AI 功能（RL、多智能体）
- 企业功能
### Phase 2-5：未来工作
使用适当的 `roadmap: phase-X` 标签标记并添加到 backlog。
---
## 🎫 Issue 模板
我们有这些 issue 模板：
### 1. Bug 报告
- 用于 bug 和错误
- 必须包含重现步骤
- 标签：`type: bug`
### 2. 功能请求
- 用于新功能
- 必须包含使用场景和好处
- 标签：`type: feature`
### 3. 悬赏认领
- 认领悬赏时使用
- 必须引用悬赏 issue
- 标签：`bounty: claimed`
### 4. 安全漏洞
- 用于安全问题（私密）
- 遵循负责任的披露
- 标签：`type: security`
**缺少模板？**
- 使用空白 issue
- 维护者将转换为适当的模板
---
## 📈 我们跟踪的指标
### 每周指标
- **PR 指标：**
- 打开的 PR 数量
- 合并的 PR 数量
- 平均首次审核时间
- 平均合并时间
- **Issue 指标：**
- 打开的 issue 数量
- 关闭的 issue 数量
- Issue backlog 大小
- 按优先级/类型/区域分类的 issue
- **社区指标：**
- 新贡献者
- 活跃贡献者
- 社区参与度（评论、反应）
### 每月指标
- **路线图进度：**
- 每个阶段的完成百分比
- 已完成 vs 计划项目
- 阻塞因素和风险
- **代码质量：**
- 测试覆盖率
- 每个 PR 的代码审核评论数
- Bug 修复 vs 功能比率
- **悬赏计划：**
- 创建的悬赏
- 认领的悬赏
- 支付的悬赏
- 平均完成时间
---
## 🤖 自动化
我们使用 GitHub Actions 进行自动化：
### PR 自动化
- **基于文件变更的自动标签**
- **PR 大小标签**（small/medium/large）
- **CI 检查**（测试、linting、构建）
- **安全扫描**（Trivy、Gitleaks）
- **Conventional commit 验证**
### Issue 自动化
- **过期 issue 检测**（30天不活动后关闭）
- **使用 "bounty" 关键字时自动悬赏标签**
- **使用 issue 相似性的重复检测**
### 发布自动化
- **从 conventional commits 生成 Changelog**
- **基于 commit 类型的版本升级**
- **自动生成发布说明**
- **部署到 staging/production**
---
## 🔄 定期任务
### 每日
- ✅ 分类新的 issue/PR
- ✅ 审查紧急 PR
- ✅ 回应社区问题
### 每周
- ✅ Sprint 计划（星期一）
- ✅ Sprint 回顾（星期五）
- ✅ 审查指标仪表板
- ✅ 更新项目看板
### 每月
- ✅ 路线图进度回顾
- ✅ 社区更新帖子
- ✅ 悬赏计划回顾
- ✅ 依赖更新
- ✅ 安全审计
### 每季度
- ✅ 路线图更新
- ✅ 主要版本规划
- ✅ 贡献者表彰
- ✅ 文档审计
---
## 📞 沟通渠道
### 内部（维护者）
- **GitHub Discussions：** 架构决策、RFC
- **私人频道：** 敏感讨论、悬赏支付
- **每周同步：** Sprint 计划和回顾
### 外部（社区）
- **Telegram：** [@nofx_dev_community](https://t.me/nofx_dev_community)
- **GitHub Issues：** Bug 报告、功能请求
- **GitHub Discussions：** 一般问题、想法
- **Twitter：** [@nofx_ai](https://x.com/nofx_ai) - 公告
---
## 🎓 新维护者入职
### 新维护者检查清单
- [ ] 添加到 GitHub 组织
- [ ] 授予仓库写入权限
- [ ] 添加到私人维护者频道
- [ ] 介绍给团队
- [ ] 阅读 `/docs/maintainers/` 中的所有文档
- [ ] 跟随有经验的维护者 1 个 Sprint
- [ ] 首次单独 PR 审核（有备份审核者）
- [ ] 首次单独 issue 分类
- [ ] 首次参与 Sprint 计划
### 期望
**时间投入：**
- 每周约 5-10 小时
- 参与 Sprint 计划/回顾
- 在 SLA 内回应分配的 issue/PR
**职责：**
- 代码审核
- Issue 分类
- 社区支持
- 文档维护
---
## 🏆 贡献者表彰
### 每月表彰
**在社区更新中聚焦：**
- 顶级贡献者
- 本月最佳 PR
- 最有帮助的社区成员
### 每季度表彰
**贡献者等级系统：**
- 🥇 **核心贡献者** - 20+ 个已合并 PR
- 🥈 **活跃贡献者** - 10+ 个已合并 PR
- 🥉 **贡献者** - 5+ 个已合并 PR
- ⭐ **首次贡献者** - 1+ 个已合并 PR
**福利：**
- 在 README 中表彰
- 邀请加入私人 Discord
- 早期访问功能
- 周边商品（核心贡献者）
---
## 📚 资源
### 内部文档
- [PR 审核指南](PR_REVIEW_GUIDE.zh-CN.md)
- [安全政策](../../SECURITY.md)
- [行为准则](../../CODE_OF_CONDUCT.md)
### 外部资源
- [GitHub 项目管理](https://docs.github.com/en/issues/planning-and-tracking-with-projects)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [语义化版本](https://semver.org/)
---
## 🤔 问题？
在维护者频道联系我们或开启讨论。
**让我们一起构建令人惊叹的产品！🚀**

458
docs/maintainers/PR_REVIEW_GUIDE.md Normal file
View File

@@ -0,0 +1,458 @@
# 🔍 PR Review Guide for Maintainers
**Language:** [English](PR_REVIEW_GUIDE.md) | [中文](PR_REVIEW_GUIDE.zh-CN.md)
This guide is for NOFX maintainers reviewing pull requests.
---
## 📋 Review Checklist
### 1. Initial Triage (Within 24 hours)
- [ ] **Check PR alignment with roadmap**
- Does it fit into our current priorities?
- Is it in the [roadmap](../roadmap/README.md)?
- If not, should we accept it anyway?
- [ ] **Verify PR completeness**
- All sections of PR template filled?
- Clear description of changes?
- Related issues linked?
- Screenshots/demo for UI changes?
- [ ] **Apply appropriate labels**
- Priority: critical/high/medium/low
- Type: bug/feature/enhancement/docs
- Area: frontend/backend/exchange/ai/security
- Status: needs review/needs changes
- [ ] **Assign reviewers**
- Assign based on area of expertise
- At least 1 maintainer review required
### 2. Code Review
#### A. Functionality Review
```markdown
✅ **Questions to Ask:**
- Does it solve the stated problem?
- Are edge cases handled?
- Will this break existing functionality?
- Is the approach correct for our architecture?
- Are there better alternatives?
```
**Testing:**
- [ ] All CI checks passed?
- [ ] Manual testing performed by contributor?
- [ ] Test coverage adequate?
- [ ] Tests are meaningful (not just for coverage)?
#### B. Code Quality Review
**Go Backend Code:**
```go
// ❌ Bad - Reject
func GetData(a, b string) interface{} {
d := doSomething(a, b)
return d
}
// ✅ Good - Approve
func GetAccountBalance(apiKey, secretKey string) (*Balance, error) {
if apiKey == "" || secretKey == "" {
return nil, fmt.Errorf("API credentials required")
}
balance, err := client.FetchBalance(apiKey, secretKey)
if err != nil {
return nil, fmt.Errorf("failed to fetch balance: %w", err)
}
return balance, nil
}
```
**Check for:**
- [ ] Meaningful variable/function names
- [ ] Proper error handling (no ignored errors)
- [ ] Comments for complex logic
- [ ] No hardcoded values (use constants/config)
- [ ] Follows Go idioms and conventions
- [ ] No unnecessary complexity
**TypeScript/React Frontend Code:**
```typescript
// ❌ Bad - Reject
const getData = (data: any) => {
return data.map(d => <div>{d.name}</div>)
}
// ✅ Good - Approve
interface Trader {
id: string;
name: string;
status: 'running' | 'stopped';
}
const TraderList: React.FC<{ traders: Trader[] }> = ({ traders }) => {
return (
<div className="trader-list">
{traders.map(trader => (
<TraderCard key={trader.id} trader={trader} />
))}
</div>
);
};
```
**Check for:**
- [ ] Type safety (no `any` unless absolutely necessary)
- [ ] Proper React patterns (hooks, functional components)
- [ ] Component reusability
- [ ] Accessibility (a11y) considerations
- [ ] Performance optimizations (memoization where needed)
#### C. Security Review
**Critical Checks:**
```go
// 🚨 REJECT - Security Issue
func Login(username, password string) {
query := "SELECT * FROM users WHERE username='" + username + "'" // SQL Injection!
db.Query(query)
}
// ✅ APPROVE - Secure
func Login(username, password string) error {
query := "SELECT * FROM users WHERE username = ?"
row := db.QueryRow(query, username) // Parameterized query
// ... proper password verification with bcrypt
}
```
- [ ] No SQL injection vulnerabilities
- [ ] No XSS vulnerabilities in frontend
- [ ] API keys/secrets not hardcoded
- [ ] User inputs properly validated
- [ ] Authentication/authorization properly handled
- [ ] No sensitive data in logs
- [ ] Dependencies have no known vulnerabilities
#### D. Performance Review
- [ ] No obvious performance issues
- [ ] Database queries optimized (indexes, no N+1 queries)
- [ ] No unnecessary API calls
- [ ] Proper caching where applicable
- [ ] No memory leaks
### 3. Documentation Review
- [ ] Code comments for complex logic
- [ ] README updated if needed
- [ ] API documentation updated (if API changes)
- [ ] Migration guide for breaking changes
- [ ] Changelog entry (for significant changes)
### 4. Testing Review
- [ ] Unit tests for new functions
- [ ] Integration tests for new features
- [ ] Tests actually test the functionality (not just coverage)
- [ ] Test names are descriptive
- [ ] Mock data is realistic
---
## 🏷️ Label Management
### Priority Assignment
Use these criteria to assign priority:
**Critical:**
- Security vulnerabilities
- Production-breaking bugs
- Data loss issues
**High:**
- Major bugs affecting many users
- High-priority roadmap features
- Performance issues
**Medium:**
- Regular bug fixes
- Standard feature requests
- Refactoring
**Low:**
- Minor improvements
- Code style changes
- Non-urgent documentation
### Status Workflow
```
needs review → in review → needs changes → needs review → approved → merged
↓
on hold
```
**Status Labels:**
- `status: needs review` - Ready for initial review
- `status: in progress` - Being actively reviewed
- `status: needs changes` - Reviewer requested changes
- `status: on hold` - Waiting for discussion/decision
- `status: blocked` - Blocked by another PR/issue
---
## 💬 Providing Feedback
### Writing Good Review Comments
**❌ Bad Comments:**
```
This is wrong.
Change this.
Why did you do this?
```
**✅ Good Comments:**
```
This approach might cause issues with concurrent requests.
Consider using a mutex or atomic operations here.
Suggestion: Extract this logic into a separate function for better testability:
```go
func validateTraderConfig(config *TraderConfig) error {
// validation logic
}
```
Question: Have you considered using the existing `ExchangeClient` interface
instead of creating a new one? This would maintain consistency with the rest
of the codebase.
```
### Comment Types
**🔴 Blocking (must be addressed):**
```markdown
**BLOCKING:** This introduces a SQL injection vulnerability.
Please use parameterized queries instead.
```
**🟡 Non-blocking (suggestions):**
```markdown
**Suggestion:** Consider using `strings.Builder` here for better performance
when concatenating many strings.
```
**🟢 Praise (encourage good practices):**
```markdown
**Nice!** Great use of context for timeout handling. This is exactly what
we want to see.
```
### Questions vs Directives
**❌ Directive (can feel demanding):**
```
Change this to use the factory pattern.
Add tests for this function.
```
**✅ Question (more collaborative):**
```
Would the factory pattern be a better fit here? It might make testing easier.
Could you add a test case for the error path? I want to make sure we handle
failures gracefully.
```
---
## ⏱️ Response Time Guidelines
| PR Type | Initial Review | Follow-up | Merge Decision |
|---------|---------------|-----------|----------------|
| **Critical Bug** | 4 hours | 2 hours | Same day |
| **Bounty PR** | 24 hours | 12 hours | 2-3 days |
| **Feature** | 2-3 days | 1-2 days | 3-5 days |
| **Documentation** | 2-3 days | 1-2 days | 3-5 days |
| **Large PR** | 3-5 days | 2-3 days | 5-7 days |
---
## ✅ Approval Criteria
A PR should be approved when:
1. **Functionality**
- ✅ Solves the stated problem
- ✅ No regression in existing features
- ✅ Edge cases handled
2. **Quality**
- ✅ Follows code standards
- ✅ Well-structured and readable
- ✅ Adequate test coverage
3. **Security**
- ✅ No security vulnerabilities
- ✅ Inputs validated
- ✅ Secrets properly managed
4. **Documentation**
- ✅ Code commented where needed
- ✅ Docs updated if applicable
5. **Process**
- ✅ All CI checks pass
- ✅ All review comments addressed
- ✅ Rebased on latest dev branch
---
## 🚫 Rejection Criteria
Reject a PR if:
**Immediate Rejection:**
- 🔴 Introduces security vulnerabilities
- 🔴 Contains malicious code
- 🔴 Violates Code of Conduct
- 🔴 Contains plagiarized code
- 🔴 Hardcoded API keys or secrets
**Request Changes:**
- 🟡 Poor code quality (after feedback ignored)
- 🟡 No tests for new features
- 🟡 Breaking changes without migration path
- 🟡 Doesn't align with roadmap (without prior discussion)
- 🟡 Incomplete (missing critical parts)
**Close with Explanation:**
- 🟠 Duplicate functionality
- 🟠 Out of scope for project
- 🟠 Better alternative already exists
- 🟠 Contributor unresponsive for >2 weeks
---
## 🎯 Special Case Reviews
### Bounty PRs
Extra care needed:
- [ ] All acceptance criteria met?
- [ ] Demo video/screenshots provided?
- [ ] Working as specified in bounty issue?
- [ ] Payment info discussed privately?
- [ ] Priority review (24h turnaround)
### Breaking Changes
- [ ] Migration guide provided?
- [ ] Deprecation warnings added?
- [ ] Version bump planned?
- [ ] Backward compatibility considered?
- [ ] RFC (Request for Comments) created for major changes?
### Security PRs
- [ ] Verified by security-focused reviewer?
- [ ] No public disclosure of vulnerability?
- [ ] Coordinated disclosure if needed?
- [ ] Security advisory prepared?
- [ ] Patch release planned?
---
## 🔄 Merge Guidelines
### When to Merge
Merge when:
- ✅ At least 1 approval from maintainer
- ✅ All CI checks passing
- ✅ All conversations resolved
- ✅ No requested changes pending
- ✅ Rebased on latest target branch
### Merge Strategy
**Squash Merge** (default for most PRs):
- Small bug fixes
- Single-feature PRs
- Documentation updates
- Keeps git history clean
**Merge Commit** (for complex PRs):
- Multi-commit features with logical commits
- Preserve commit history
- Large refactoring with atomic commits
**Rebase and Merge** (rarely):
- When linear history is important
- Commits are already well-structured
### Merge Commit Message
Format:
```
<type>(<scope>): <PR title> (#123)
Brief description of changes.
- Key change 1
- Key change 2
Co-authored-by: Contributor Name <email@example.com>
```
---
## 📊 Review Metrics to Track
Monitor these metrics monthly:
- Average time to first review
- Average time to merge
- PR acceptance rate
- Number of PRs by type (bug/feature/docs)
- Number of PRs by area (frontend/backend/exchange)
- Contributor retention rate
---
## 🙋 Questions?
If unsure about a PR:
1. **Ask other maintainers** in private channel
2. **Request more context** from contributor
3. **Mark as "on hold"** and add to next maintainer sync
4. **When in doubt, be conservative** - better to ask than approve something risky
---
## 🔗 Related Resources
- [Contributing Guide](../../CONTRIBUTING.md)
- [Code of Conduct](../../CODE_OF_CONDUCT.md)
- [Security Policy](../../SECURITY.md)
- [Project Roadmap](../roadmap/README.md)
---
**Remember:** Reviews should be **respectful**, **constructive**, and **educational**.
We're building a community, not just code. 🚀

457
docs/maintainers/PR_REVIEW_GUIDE.zh-CN.md Normal file
View File

@@ -0,0 +1,457 @@
# 🔍 维护者 PR 审核指南
**语言：** [English](PR_REVIEW_GUIDE.md) | [中文](PR_REVIEW_GUIDE.zh-CN.md)
本指南适用于审核 pull request 的 NOFX 维护者。
---
## 📋 审核清单
### 1. 初步分类（24小时内）
- [ ] **检查 PR 与路线图的一致性**
- 是否符合我们当前的优先级？
- 是否在[路线图](../roadmap/README.zh-CN.md)中？
- 如果不在，我们是否应该接受它？
- [ ] **验证 PR 完整性**
- PR 模板的所有部分都已填写？
- 变更描述清晰？
- 相关 issue 已链接？
- UI 变更有截图/演示？
- [ ] **应用适当的标签**
- 优先级：critical/high/medium/low
- 类型：bug/feature/enhancement/docs
- 区域：frontend/backend/exchange/ai/security
- 状态：needs review/needs changes
- [ ] **分配审核者**
- 根据专业领域分配
- 至少需要 1 个维护者审核
### 2. 代码审核
#### A. 功能审核
```markdown
✅ **要问的问题：**
- 是否解决了所述问题？
- 边界情况是否处理？
- 是否会破坏现有功能？
- 方法是否适合我们的架构？
- 是否有更好的替代方案？
```
**测试：**
- [ ] 所有 CI 检查都通过？
- [ ] 贡献者进行了手动测试？
- [ ] 测试覆盖率足够？
- [ ] 测试有意义（不只是为了覆盖率）？
#### B. 代码质量审核
**Go 后端代码：**
```go
// ❌ 差 - 拒绝
func GetData(a, b string) interface{} {
d := doSomething(a, b)
return d
}
// ✅ 好 - 批准
func GetAccountBalance(apiKey, secretKey string) (*Balance, error) {
if apiKey == "" || secretKey == "" {
return nil, fmt.Errorf("API credentials required")
}
balance, err := client.FetchBalance(apiKey, secretKey)
if err != nil {
return nil, fmt.Errorf("failed to fetch balance: %w", err)
}
return balance, nil
}
```
**检查项：**
- [ ] 有意义的变量/函数名
- [ ] 正确的错误处理（没有忽略错误）
- [ ] 复杂逻辑有注释
- [ ] 没有硬编码值（使用常量/配置）
- [ ] 遵循 Go 习惯用法和约定
- [ ] 没有不必要的复杂性
**TypeScript/React 前端代码：**
```typescript
// ❌ 差 - 拒绝
const getData = (data: any) => {
return data.map(d => <div>{d.name}</div>)
}
// ✅ 好 - 批准
interface Trader {
id: string;
name: string;
status: 'running' | 'stopped';
}
const TraderList: React.FC<{ traders: Trader[] }> = ({ traders }) => {
return (
<div className="trader-list">
{traders.map(trader => (
<TraderCard key={trader.id} trader={trader} />
))}
</div>
);
};
```
**检查项：**
- [ ] 类型安全（除非绝对必要，否则不使用 `any`）
- [ ] 正确的 React 模式（hooks、函数式组件）
- [ ] 组件可重用性
- [ ] 可访问性（a11y）考虑
- [ ] 性能优化（需要时使用 memoization）
#### C. 安全审核
**关键检查：**
```go
// 🚨 拒绝 - 安全问题
func Login(username, password string) {
query := "SELECT * FROM users WHERE username='" + username + "'" // SQL 注入！
db.Query(query)
}
// ✅ 批准 - 安全
func Login(username, password string) error {
query := "SELECT * FROM users WHERE username = ?"
row := db.QueryRow(query, username) // 参数化查询
// ... 使用 bcrypt 进行正确的密码验证
}
```
- [ ] 没有 SQL 注入漏洞
- [ ] 前端没有 XSS 漏洞
- [ ] API 密钥/密码没有硬编码
- [ ] 用户输入已正确验证
- [ ] 认证/授权正确处理
- [ ] 日志中没有敏感数据
- [ ] 依赖项没有已知漏洞
#### D. 性能审核
- [ ] 没有明显的性能问题
- [ ] 数据库查询已优化（索引、没有 N+1 查询）
- [ ] 没有不必要的 API 调用
- [ ] 适当的缓存
- [ ] 没有内存泄漏
### 3. 文档审核
- [ ] 复杂逻辑有代码注释
- [ ] 如果需要，README 已更新
- [ ] API 文档已更新（如有 API 变更）
- [ ] 破坏性变更有迁移指南
- [ ] Changelog 条目（对于重大变更）
### 4. 测试审核
- [ ] 新函数有单元测试
- [ ] 新功能有集成测试
- [ ] 测试确实测试了功能（不只是覆盖率）
- [ ] 测试名称具有描述性
- [ ] 模拟数据真实
---
## 🏷️ 标签管理
### 优先级分配
使用这些标准来分配优先级：
**Critical（严重）：**
- 安全漏洞
- 生产环境破坏性 bug
- 数据丢失问题
**High（高）：**
- 影响许多用户的重大 bug
- 高优先级路线图功能
- 性能问题
**Medium（中）：**
- 常规 bug 修复
- 标准功能请求
- 重构
**Low（低）：**
- 次要改进
- 代码风格变更
- 非紧急文档
### 状态工作流
```
needs review → in review → needs changes → needs review → approved → merged
↓
on hold
```
**状态标签：**
- `status: needs review` - 准备初次审核
- `status: in progress` - 正在积极审核
- `status: needs changes` - 审核者请求更改
- `status: on hold` - 等待讨论/决定
- `status: blocked` - 被另一个 PR/issue 阻塞
---
## 💬 提供反馈
### 编写好的审核评论
**❌ 差的评论：**
```
这是错的。
改这个。
你为什么这样做？
```
**✅ 好的评论：**
```
这种方法可能会导致并发请求的问题。
考虑在这里使用互斥锁或原子操作。
建议：将此逻辑提取到单独的函数中以提高可测试性：
```go
func validateTraderConfig(config *TraderConfig) error {
// 验证逻辑
}
```
问题：你是否考虑过使用现有的 `ExchangeClient` 接口
而不是创建新接口？这将与代码库的其余部分保持一致。
```
### 评论类型
**🔴 阻塞性（必须解决）：**
```markdown
**阻塞性：** 这引入了 SQL 注入漏洞。
请改用参数化查询。
```
**🟡 非阻塞性（建议）：**
```markdown
**建议：** 考虑在这里使用 `strings.Builder` 以提高
连接多个字符串时的性能。
```
**🟢 赞扬（鼓励好的做法）：**
```markdown
**很好！** 很好地使用 context 进行超时处理。这正是
我们想看到的。
```
### 问题 vs 指令
**❌ 指令（可能感觉强硬）：**
```
改用工厂模式。
为这个函数添加测试。
```
**✅ 问题（更协作）：**
```
工厂模式在这里会更合适吗？它可能会使测试更容易。
你能为错误路径添加一个测试用例吗？我想确保我们
优雅地处理失败。
```
---
## ⏱️ 响应时间指南
| PR 类型 | 初次审核 | 后续审核 | 合并决定 |
|---------|----------|----------|----------|
| **严重 Bug** | 4 小时 | 2 小时 | 当天 |
| **悬赏 PR** | 24 小时 | 12 小时 | 2-3 天 |
| **功能** | 2-3 天 | 1-2 天 | 3-5 天 |
| **文档** | 2-3 天 | 1-2 天 | 3-5 天 |
| **大型 PR** | 3-5 天 | 2-3 天 | 5-7 天 |
---
## ✅ 批准标准
PR 应在以下情况下批准：
1. **功能性**
- ✅ 解决了所述问题
- ✅ 现有功能没有退化
- ✅ 边界情况已处理
2. **质量**
- ✅ 遵循代码标准
- ✅ 结构良好且可读
- ✅ 测试覆盖率足够
3. **安全性**
- ✅ 没有安全漏洞
- ✅ 输入已验证
- ✅ 密钥管理正确
4. **文档**
- ✅ 需要的地方有代码注释
- ✅ 文档已更新（如适用）
5. **流程**
- ✅ 所有 CI 检查通过
- ✅ 所有审核评论已处理
- ✅ 已基于最新 dev 分支 rebase
---
## 🚫 拒绝标准
在以下情况下拒绝 PR：
**立即拒绝：**
- 🔴 引入安全漏洞
- 🔴 包含恶意代码
- 🔴 违反行为准则
- 🔴 包含抄袭代码
- 🔴 硬编码 API 密钥或密码
**请求更改：**
- 🟡 代码质量差（反馈被忽略后）
- 🟡 新功能没有测试
- 🟡 没有迁移路径的破坏性变更
- 🟡 与路线图不一致（未经事先讨论）
- 🟡 不完整（缺少关键部分）
**关闭并说明：**
- 🟠 重复功能
- 🟠 超出项目范围
- 🟠 已存在更好的替代方案
- 🟠 贡献者 >2 周无响应
---
## 🎯 特殊情况审核
### 悬赏 PR
需要额外注意：
- [ ] 所有验收标准都满足？
- [ ] 提供了演示视频/截图？
- [ ] 按悬赏 issue 中的规定工作？
- [ ] 私下讨论了付款信息？
- [ ] 优先审核（24小时周转）
### 破坏性变更
- [ ] 提供了迁移指南？
- [ ] 添加了弃用警告？
- [ ] 计划了版本升级？
- [ ] 考虑了向后兼容性？
- [ ] 为重大变更创建了 RFC？
### 安全 PR
- [ ] 由专注于安全的审核者验证？
- [ ] 没有公开披露漏洞？
- [ ] 如需要，协调披露？
- [ ] 准备了安全公告？
- [ ] 计划了补丁发布？
---
## 🔄 合并指南
### 何时合并
满足以下条件时合并：
- ✅ 至少 1 个维护者批准
- ✅ 所有 CI 检查通过
- ✅ 所有对话已解决
- ✅ 没有待处理的请求更改
- ✅ 已基于最新目标分支 rebase
### 合并策略
**Squash Merge**（大多数 PR 的默认策略）：
- 小型 bug 修复
- 单功能 PR
- 文档更新
- 保持 git 历史清洁
**Merge Commit**（复杂 PR）：
- 具有逻辑提交的多提交功能
- 保留提交历史
- 具有原子提交的大型重构
**Rebase and Merge**（很少使用）：
- 线性历史很重要时
- 提交已经结构良好
### 合并提交信息
格式：
```
<type>(<scope>): <PR 标题> (#123)
变更的简要描述。
- 关键变更 1
- 关键变更 2
Co-authored-by: 贡献者姓名 <email@example.com>
```
---
## 📊 要跟踪的审核指标
每月监控这些指标：
- 平均首次审核时间
- 平均合并时间
- PR 接受率
- 按类型分类的 PR 数量（bug/feature/docs）
- 按区域分类的 PR 数量（frontend/backend/exchange）
- 贡献者留存率
---
## 🙋 问题？
如果对 PR 不确定：
1. **询问其他维护者**在私人频道
2. **向贡献者请求更多上下文**
3. **标记为"on hold"**并添加到下次维护者同步
4. **如有疑问，保守一点** - 问比批准有风险的东西更好
---
## 🔗 相关资源
- [贡献指南](../../CONTRIBUTING.md)
- [行为准则](../../CODE_OF_CONDUCT.md)
- [安全政策](../../SECURITY.md)
- [项目路线图](../roadmap/README.zh-CN.md)
---
**记住：** 审核应该是**尊重的**、**建设性的**和**教育性的**。
我们在构建社区，而不仅仅是代码。🚀

51
docs/maintainers/README.md Normal file
View File

@@ -0,0 +1,51 @@
# 📚 Maintainer Documentation
**Language:** [English](README.md) | [中文](README.zh-CN.md)
This directory contains documentation for NOFX project maintainers and contributors who want to understand our processes.
---
## 📖 Documentation
| Document | Description |
|----------|-------------|
| [PR_REVIEW_GUIDE.md](PR_REVIEW_GUIDE.md) | Guide for reviewing pull requests |
| [PROJECT_MANAGEMENT.md](PROJECT_MANAGEMENT.md) | Project management workflow and processes |
| [SETUP_GUIDE.md](SETUP_GUIDE.md) | Setup guide for the PR management system |
**Available in:** 🇬🇧 English | 🇨🇳 中文
---
## 🎯 For New Maintainers
If you're a new maintainer, start here:
1. **Read the documentation** (listed above) to understand the review process
2. **Shadow an experienced maintainer** for 1-2 weeks
3. **Start with simple reviews** before handling complex PRs
4. **Ask questions** in the maintainer channel
---
## 🤝 For Contributors
These documents are also helpful for contributors who want to:
- Understand our review standards
- Learn our project management workflow
- See how we prioritize work
Everything here is transparent and designed to help you contribute successfully!
---
## 📞 Questions?
- **Public questions:** Use [GitHub Discussions](https://github.com/tinkle-community/nofx/discussions)
- **Maintainer questions:** Use the maintainer channel
- **Migration questions:** See [Migration Announcement](../community/MIGRATION_ANNOUNCEMENT.md)
---
**Remember:** We're building an open, welcoming community. Documentation should empower contributors while maintaining project quality. 🚀

51
docs/maintainers/README.zh-CN.md Normal file
View File

@@ -0,0 +1,51 @@
# 📚 维护者文档
**语言：** [English](README.md) | [中文](README.zh-CN.md)
此目录包含 NOFX 项目维护者和想要了解我们流程的贡献者的文档。
---
## 📖 文档
| 文档 | 描述 |
|------|------|
| [PR_REVIEW_GUIDE.md](PR_REVIEW_GUIDE.md) | PR 审核指南 |
| [PROJECT_MANAGEMENT.md](PROJECT_MANAGEMENT.md) | 项目管理工作流程和流程 |
| [SETUP_GUIDE.md](SETUP_GUIDE.md) | PR 管理系统设置指南 |
**可用语言：** 🇬🇧 English | 🇨🇳 中文
---
## 🎯 对于新维护者
如果你是新维护者，从这里开始：
1. **阅读文档**（上面列出的）以了解审核流程
2. **跟随有经验的维护者** 1-2 周
3. **从简单的审核开始**，然后再处理复杂的 PR
4. **在维护者频道提问**
---
## 🤝 对于贡献者
这些文档对想要以下内容的贡献者也很有帮助：
- 了解我们的审核标准
- 学习我们的项目管理工作流程
- 了解我们如何排定工作优先级
这里的一切都是透明的，旨在帮助你成功贡献！
---
## 📞 问题？
- **公开问题：** 使用 [GitHub Discussions](https://github.com/tinkle-community/nofx/discussions)
- **维护者问题：** 使用维护者频道
- **迁移问题：** 查看[迁移公告](../community/MIGRATION_ANNOUNCEMENT.zh-CN.md)
---
**记住：** 我们正在建立一个开放、热情的社区。文档应该赋能贡献者，同时保持项目质量。🚀

381
docs/maintainers/SETUP_GUIDE.md Normal file
View File

@@ -0,0 +1,381 @@
# 🚀 PR Management System Setup Guide
**Language:** [English](SETUP_GUIDE.md) | [中文](SETUP_GUIDE.zh-CN.md)
This guide will help you set up and activate the complete PR management system for NOFX.
---
## 📦 What's Included
The PR management system includes:
### 1. **Documentation**
- ✅ `CONTRIBUTING.md` - Contributor guidelines
- ✅ `docs/maintainers/PR_REVIEW_GUIDE.md` - Reviewer guidelines
- ✅ `docs/maintainers/PROJECT_MANAGEMENT.md` - Project management workflow
- ✅ `docs/maintainers/SETUP_GUIDE.md` - This file
### 2. **GitHub Configuration**
- ✅ `.github/PULL_REQUEST_TEMPLATE.md` - PR template (already exists)
- ✅ `.github/labels.yml` - Label definitions
- ✅ `.github/labeler.yml` - Auto-labeling rules
- ✅ `.github/workflows/pr-checks.yml` - Automated PR checks
### 3. **Automation**
- ✅ Automatic PR labeling
- ✅ PR size checking
- ✅ CI/CD tests
- ✅ Security scanning
- ✅ Commit message validation
---
## 🔧 Setup Steps
### Step 1: Sync GitHub Labels
Create the labels defined in `.github/labels.yml`:
```bash
# Option 1: Using gh CLI (recommended)
gh label list # See current labels
gh label delete <label-name> # Remove old labels if needed
gh label create "priority: critical" --color "d73a4a" --description "Critical priority"
# ... repeat for all labels in labels.yml
# Option 2: Use GitHub Labeler Action (automated)
# The workflow will sync labels automatically on push
```
**Or use the GitHub Labeler Action** (add to `.github/workflows/sync-labels.yml`):
```yaml
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
```
### Step 2: Enable GitHub Actions
1. Go to **Settings → Actions → General**
2. Enable **"Allow all actions and reusable workflows"**
3. Set **Workflow permissions** to **"Read and write permissions"**
4. Check **"Allow GitHub Actions to create and approve pull requests"**
### Step 3: Set Up Branch Protection Rules
**For `main` branch:**
1. Go to **Settings → Branches → Add rule**
2. Branch name pattern: `main`
3. Configure:
- ✅ Require a pull request before merging
- ✅ Require approvals: **1**
- ✅ Require status checks to pass before merging
- Select: `Backend Tests (Go)`
- Select: `Frontend Tests (React/TypeScript)`
- Select: `Security Scan`
- ✅ Require conversation resolution before merging
- ✅ Do not allow bypassing the above settings
- ❌ Allow force pushes (disabled)
- ❌ Allow deletions (disabled)
**For `dev` branch:**
1. Same as above, but with:
- Require approvals: **1**
- Less strict (allow maintainers to bypass if needed)
### Step 4: Create GitHub Projects
1. Go to **Projects → New project**
2. Create **"NOFX Development"** board
- Template: Board
- Add columns: `Backlog`, `Triaged`, `In Progress`, `In Review`, `Done`
- Add views: Sprint, Roadmap, By Area, Priority
3. Create **"Bounty Program"** board
- Template: Board
- Add columns: `Available`, `Claimed`, `In Progress`, `Under Review`, `Paid`
### Step 5: Enable Discussions (Optional but Recommended)
1. Go to **Settings → General → Features**
2. Enable **"Discussions"**
3. Create categories:
- 💬 **General** - General discussions
- 💡 **Ideas** - Feature ideas and suggestions
- 🙏 **Q&A** - Questions and answers
- 📢 **Announcements** - Important updates
- 🗳️ **Polls** - Community polls
### Step 6: Configure Issue Templates
The templates already exist in `.github/ISSUE_TEMPLATE/`. Verify they're working:
1. Go to **Issues → New issue**
2. You should see:
- 🐛 Bug Report
- ✨ Feature Request
- 💰 Bounty Claim
If not showing, check files are properly formatted YAML with frontmatter.
### Step 7: Set Up Code Owners (Optional)
Create `.github/CODEOWNERS`:
```
# Global owners
* @tinkle @zack
# Frontend
/web/ @frontend-lead
# Exchange integrations
/internal/exchange/ @exchange-lead
# AI components
/internal/ai/ @ai-lead
# Documentation
/docs/ @tinkle @zack
*.md @tinkle @zack
```
### Step 8: Configure Notifications
**For Maintainers:**
1. Go to **Settings → Notifications**
2. Enable:
- ✅ Pull request reviews
- ✅ Pull request pushes
- ✅ Comments on issues and PRs
- ✅ New issues
- ✅ Security alerts
3. Set up email filters to organize notifications
**For Repository:**
1. Go to **Settings → Webhooks** (if integrating with Slack/Discord)
2. Add webhook for notifications
---
## 📋 Post-Setup Checklist
After setup, verify:
- [ ] Labels are created and visible
- [ ] Branch protection rules are active
- [ ] GitHub Actions workflows run on new PR
- [ ] Auto-labeling works (create a test PR)
- [ ] PR template shows when creating PR
- [ ] Issue templates show when creating issue
- [ ] Projects boards are accessible
- [ ] CONTRIBUTING.md is linked in README
---
## 🎯 How to Use the System
### For Contributors
1. **Read** [CONTRIBUTING.md](../../../CONTRIBUTING.md)
2. **Check** [Roadmap](../../roadmap/README.md) for priorities
3. **Open issue** or find existing one
4. **Create PR** using the template
5. **Address review feedback**
6. **Celebrate** when merged! 🎉
### For Maintainers
1. **Daily:** Triage new issues/PRs (15 min)
2. **Daily:** Review assigned PRs
3. **Weekly:** Sprint planning (Monday) and review (Friday)
4. **Follow:** [PR Review Guide](PR_REVIEW_GUIDE.md)
5. **Follow:** [Project Management Guide](PROJECT_MANAGEMENT.md)
### For Bounty Hunters
1. **Check** bounty issues with `bounty` label
2. **Claim** by commenting on issue
3. **Complete** within deadline
4. **Submit PR** with bounty claim section filled
5. **Get paid** after merge
---
## 🔍 Testing the System
### Test 1: Create a Test PR
```bash
# Create a test branch
git checkout -b test/pr-system-check
# Make a small change
echo "# Test" >> TEST.md
# Commit and push
git add TEST.md
git commit -m "test: verify PR automation system"
git push origin test/pr-system-check
# Create PR on GitHub
# Verify:
# - PR template loads
# - Auto-labels are applied
# - CI checks run
# - Size label is added
```
### Test 2: Create a Test Issue
1. Go to **Issues → New issue**
2. Select **Bug Report**
3. Fill in template
4. Submit
5. Verify:
- Template renders correctly
- Issue can be labeled
- Issue appears in project board
### Test 3: Test Auto-Labeling
Create PRs that change files in different areas:
```bash
# Test 1: Frontend changes
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
# Should get "area: frontend" label
# Test 2: Backend changes
git checkout -b test/backend-label
touch internal/test.go
git add . && git commit -m "test: backend labeling"
git push origin test/backend-label
# Should get "area: backend" label
```
---
## 🐛 Troubleshooting
### Issue: Labels not syncing
**Solution:**
```bash
# Delete all existing labels first
gh label list --json name --jq '.[].name' | xargs -I {} gh label delete "{}" --yes
# Then create from labels.yml manually or via action
```
### Issue: GitHub Actions not running
**Check:**
1. Actions are enabled in repository settings
2. Workflow files are in `.github/workflows/`
3. YAML syntax is valid
4. Permissions are set correctly
**Debug:**
```bash
# Validate workflow locally
act pull_request # Using 'act' tool
```
### Issue: Branch protection blocking PRs
**Check:**
1. Required checks are defined in workflow
2. Check names match exactly
3. Checks are completing (not stuck)
**Temporary fix:**
- Maintainers can bypass if urgent
- Adjust protection rules if too strict
### Issue: Auto-labeler not working
**Check:**
1. `.github/labeler.yml` exists and valid YAML
2. Labels defined in labeler.yml exist in repository
3. Workflow has `pull-requests: write` permission
---
## 📊 Monitoring and Maintenance
### Weekly Review
Check these metrics every week:
```bash
# Using gh CLI
gh pr list --state all --json number,createdAt,closedAt
gh issue list --state all --json number,createdAt,closedAt
# Or use GitHub Insights
# Repository → Insights → Pulse, Contributors, Traffic
```
### Monthly Maintenance
- [ ] Review and update labels if needed
- [ ] Check for outdated dependencies in workflows
- [ ] Update CONTRIBUTING.md if processes change
- [ ] Review automation effectiveness
- [ ] Gather community feedback
---
## 🎓 Training Resources
### For New Contributors
- [First Contributions Guide](https://github.com/firstcontributions/first-contributions)
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Conventional Commits](https://www.conventionalcommits.org/)
### For Maintainers
- [The Art of Code Review](https://google.github.io/eng-practices/review/)
- [GitHub Project Management](https://docs.github.com/en/issues/planning-and-tracking-with-projects)
- [Maintainer Community](https://maintainers.github.com/)
---
## 🎉 You're All Set!
The PR management system is now ready to:
✅ Guide contributors with clear guidelines
✅ Automate repetitive tasks
✅ Maintain code quality
✅ Track progress systematically
✅ Scale the community
**Questions?** Reach out in the maintainer channel or open a discussion.
**Let's build an amazing community! 🚀**

381
docs/maintainers/SETUP_GUIDE.zh-CN.md Normal file
View File

@@ -0,0 +1,381 @@
# 🚀 PR 管理系统设置指南
**语言：** [English](SETUP_GUIDE.md) | [中文](SETUP_GUIDE.zh-CN.md)
本指南将帮助你为 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` 中定义的标签：
```bash
# 选项 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`）：
```yaml
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](../../../CONTRIBUTING.md)
2. **查看** [路线图](../../roadmap/README.zh-CN.md)了解优先级
3. **开启 issue** 或找到现有的
4. **使用模板创建 PR**
5. **处理审核反馈**
6. **庆祝** 当合并时！🎉
### 对于维护者
1. **每日：** 分类新 issue/PR（15分钟）
2. **每日：** 审查分配的 PR
3. **每周：** Sprint 计划（周一）和回顾（周五）
4. **遵循：** [PR 审核指南](PR_REVIEW_GUIDE.zh-CN.md)
5. **遵循：** [项目管理指南](PROJECT_MANAGEMENT.zh-CN.md)
### 对于悬赏猎人
1. **查看** 带有 `bounty` 标签的悬赏 issue
2. **通过评论认领** issue
3. **在截止日期前完成**
4. **提交 PR** 并填写悬赏认领部分
5. **合并后获得报酬**
---
## 🔍 测试系统
### 测试 1：创建测试 PR
```bash
# 创建测试分支
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：
```bash
# 测试 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" 标签
```
---
## 🐛 故障排除
### 问题：标签未同步
**解决方案：**
```bash
# 首先删除所有现有标签
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. 权限设置正确
**调试：**
```bash
# 本地验证工作流
act pull_request # 使用 'act' 工具
```
### 问题：分支保护阻止 PR
**检查：**
1. 必需的检查在工作流中定义
2. 检查名称完全匹配
3. 检查正在完成（没有卡住）
**临时修复：**
- 维护者可以在紧急情况下绕过
- 如果太严格，调整保护规则
### 问题：自动标签器不工作
**检查：**
1. `.github/labeler.yml` 存在且为有效 YAML
2. labeler.yml 中定义的标签在仓库中存在
3. 工作流有 `pull-requests: write` 权限
---
## 📊 监控和维护
### 每周回顾
每周检查这些指标：
```bash
# 使用 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
- [ ] 审查自动化效果
- [ ] 收集社区反馈
---
## 🎓 培训资源
### 对于新贡献者
- [首次贡献指南](https://github.com/firstcontributions/first-contributions)
- [如何写 Git Commit 信息](https://chris.beams.io/posts/git-commit/)
- [Conventional Commits](https://www.conventionalcommits.org/)
### 对于维护者
- [代码审核的艺术](https://google.github.io/eng-practices/review/)
- [GitHub 项目管理](https://docs.github.com/en/issues/planning-and-tracking-with-projects)
- [维护者社区](https://maintainers.github.com/)
---
## 🎉 一切就绪！
PR 管理系统现在已准备好：
✅ 用清晰的指南引导贡献者
✅ 自动化重复任务
✅ 保持代码质量
✅ 系统性地跟踪进度
✅ 扩展社区
**有问题？** 在维护者频道联系我们或开启讨论。
**让我们构建令人惊叹的社区！🚀**