mirror of
https://github.com/NoFxAiOS/nofx.git
synced 2026-06-06 05:51:19 +08:00
feat: pr validation
This commit is contained in:
zbhan
272
docs/community/HOW_TO_MIGRATE_YOUR_PR.md
Normal file
272
docs/community/HOW_TO_MIGRATE_YOUR_PR.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# 🔄 How to Migrate Your PR to the New Format
|
||||
|
||||
**Language:** [English](HOW_TO_MIGRATE_YOUR_PR.md) | [中文](HOW_TO_MIGRATE_YOUR_PR.zh-CN.md)
|
||||
|
||||
This guide helps you migrate your existing PR to meet the new PR management system requirements.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Why Migrate?
|
||||
|
||||
While your existing PR **will still be reviewed and merged** under current standards, migrating it to the new format gives you:
|
||||
|
||||
✅ **Faster reviews** - Automated checks catch issues early
|
||||
✅ **Better feedback** - Clear, actionable feedback from CI
|
||||
✅ **Higher quality** - Consistent code standards
|
||||
✅ **Learning** - Understand our new contribution workflow
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Quick Check (Recommended)
|
||||
|
||||
### Step 1: Analyze Your PR
|
||||
|
||||
```bash
|
||||
# Run the PR health check (reads only, doesn't modify anything)
|
||||
./scripts/pr-check.sh
|
||||
```
|
||||
|
||||
This will analyze your PR and tell you:
|
||||
- ✅ What's good
|
||||
- ⚠️ What needs attention
|
||||
- 💡 How to fix issues
|
||||
- 📊 Overall health score
|
||||
|
||||
### Step 2: Fix Issues
|
||||
|
||||
Based on the suggestions, fix the issues manually. Common fixes:
|
||||
|
||||
```bash
|
||||
# Rebase on latest dev
|
||||
git fetch upstream && git rebase upstream/dev
|
||||
|
||||
# Format Go code
|
||||
go fmt ./...
|
||||
|
||||
# Run tests
|
||||
go test ./...
|
||||
|
||||
# Format frontend code
|
||||
cd web && npm run lint -- --fix
|
||||
```
|
||||
|
||||
### Step 3: Run Check Again
|
||||
|
||||
```bash
|
||||
# Verify all issues are fixed
|
||||
./scripts/pr-check.sh
|
||||
```
|
||||
|
||||
### Step 4: Push Changes
|
||||
|
||||
```bash
|
||||
git push -f origin <your-pr-branch>
|
||||
```
|
||||
|
||||
### What the Script Does
|
||||
|
||||
1. ✅ Syncs with latest `upstream/dev`
|
||||
2. ✅ Rebases your changes
|
||||
3. ✅ Formats Go code (`go fmt`)
|
||||
4. ✅ Runs Go linting (`go vet`)
|
||||
5. ✅ Runs tests
|
||||
6. ✅ Formats frontend code (if applicable)
|
||||
7. ✅ Pushes changes to your PR
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Manual Migration (Step by Step)
|
||||
|
||||
If you prefer to do it manually:
|
||||
|
||||
### Step 1: Sync with Upstream
|
||||
|
||||
```bash
|
||||
# Add upstream if not already added
|
||||
git remote add upstream https://github.com/tinkle-community/nofx.git
|
||||
|
||||
# Fetch latest changes
|
||||
git fetch upstream
|
||||
|
||||
# Rebase your branch
|
||||
git checkout <your-pr-branch>
|
||||
git rebase upstream/dev
|
||||
```
|
||||
|
||||
### Step 2: Backend Checks (Go)
|
||||
|
||||
```bash
|
||||
# Format Go code
|
||||
go fmt ./...
|
||||
|
||||
# Run linting
|
||||
go vet ./...
|
||||
|
||||
# Run tests
|
||||
go test ./...
|
||||
|
||||
# If you made changes, commit them
|
||||
git add .
|
||||
git commit -m "chore: format and fix backend issues"
|
||||
```
|
||||
|
||||
### Step 3: Frontend Checks (if applicable)
|
||||
|
||||
```bash
|
||||
cd web
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Fix linting issues
|
||||
npm run lint -- --fix
|
||||
|
||||
# Check types
|
||||
npm run type-check
|
||||
|
||||
# Test build
|
||||
npm run build
|
||||
|
||||
cd ..
|
||||
|
||||
# Commit any fixes
|
||||
git add .
|
||||
git commit -m "chore: fix frontend issues"
|
||||
```
|
||||
|
||||
### Step 4: Update PR Title (if needed)
|
||||
|
||||
Ensure your PR title follows [Conventional Commits](https://www.conventionalcommits.org/):
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
Examples:
|
||||
feat(exchange): add OKX integration
|
||||
fix(trader): resolve position tracking bug
|
||||
docs(readme): update installation guide
|
||||
```
|
||||
|
||||
**Types:**
|
||||
- `feat` - New feature
|
||||
- `fix` - Bug fix
|
||||
- `docs` - Documentation
|
||||
- `refactor` - Code refactoring
|
||||
- `perf` - Performance improvement
|
||||
- `test` - Test updates
|
||||
- `chore` - Build/config changes
|
||||
- `security` - Security improvements
|
||||
|
||||
### Step 5: Push Changes
|
||||
|
||||
```bash
|
||||
git push -f origin <your-pr-branch>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Checklist
|
||||
|
||||
After migrating, verify:
|
||||
|
||||
- [ ] PR is rebased on latest `dev`
|
||||
- [ ] No merge conflicts
|
||||
- [ ] Backend tests pass locally
|
||||
- [ ] Frontend builds successfully
|
||||
- [ ] PR title follows Conventional Commits format
|
||||
- [ ] All commits are meaningful
|
||||
- [ ] Changes pushed to GitHub
|
||||
|
||||
---
|
||||
|
||||
## 🤖 What Happens After Migration?
|
||||
|
||||
After you push your changes:
|
||||
|
||||
1. **Automated checks will run** (they won't block merging, just provide feedback)
|
||||
2. **You'll get a comment** with check results and suggestions
|
||||
3. **Maintainers will review** your PR with the new context
|
||||
4. **Faster review** thanks to pre-checks
|
||||
|
||||
---
|
||||
|
||||
## ❓ Troubleshooting
|
||||
|
||||
### "Rebase conflicts"
|
||||
|
||||
If you get conflicts during rebase:
|
||||
|
||||
```bash
|
||||
# Fix conflicts in your editor
|
||||
# Then:
|
||||
git add <fixed-files>
|
||||
git rebase --continue
|
||||
|
||||
# Or abort and ask for help:
|
||||
git rebase --abort
|
||||
```
|
||||
|
||||
**Need help?** Just comment on your PR and we'll assist!
|
||||
|
||||
### "Tests failing"
|
||||
|
||||
If tests fail:
|
||||
|
||||
```bash
|
||||
# Run tests to see the error
|
||||
go test ./...
|
||||
|
||||
# Fix the issue
|
||||
# Then commit and push
|
||||
git add .
|
||||
git commit -m "fix: resolve test failures"
|
||||
git push -f origin <your-pr-branch>
|
||||
```
|
||||
|
||||
### "Script not working"
|
||||
|
||||
If the migration script doesn't work:
|
||||
|
||||
1. Check you have Go and Node.js installed
|
||||
2. Try manual migration (steps above)
|
||||
3. Ask for help in your PR comments
|
||||
|
||||
---
|
||||
|
||||
## 💡 Tips
|
||||
|
||||
**Don't want to migrate?**
|
||||
- That's okay! Your PR will still be reviewed and merged
|
||||
- Migration is optional but recommended
|
||||
|
||||
**First time using Git rebase?**
|
||||
- Check our [Git guide](https://git-scm.com/book/en/v2/Git-Branching-Rebasing)
|
||||
- Ask questions in your PR - we're here to help!
|
||||
|
||||
**Want to learn more?**
|
||||
- [Contributing Guidelines](../../CONTRIBUTING.md)
|
||||
- [Migration Announcement](MIGRATION_ANNOUNCEMENT.md)
|
||||
- [PR Review Guide](../maintainers/PR_REVIEW_GUIDE.md)
|
||||
|
||||
---
|
||||
|
||||
## 📞 Need Help?
|
||||
|
||||
**Stuck on migration?**
|
||||
- Comment on your PR
|
||||
- Ask in [Telegram](https://t.me/nofx_dev_community)
|
||||
- Open a [Discussion](https://github.com/tinkle-community/nofx/discussions)
|
||||
|
||||
**We're here to help you succeed!** 🚀
|
||||
|
||||
---
|
||||
|
||||
## 🎉 After Migration
|
||||
|
||||
Once migrated:
|
||||
1. ✅ Wait for automated checks to run
|
||||
2. ✅ Address any feedback in comments
|
||||
3. ✅ Wait for maintainer review
|
||||
4. ✅ Celebrate when merged! 🎉
|
||||
|
||||
**Thank you for contributing to NOFX!**
|
||||
272
docs/community/HOW_TO_MIGRATE_YOUR_PR.zh-CN.md
Normal file
272
docs/community/HOW_TO_MIGRATE_YOUR_PR.zh-CN.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# 🔄 如何将你的 PR 迁移到新格式
|
||||
|
||||
**语言：** [English](HOW_TO_MIGRATE_YOUR_PR.md) | [中文](HOW_TO_MIGRATE_YOUR_PR.zh-CN.md)
|
||||
|
||||
本指南帮助你将现有 PR 迁移以满足新的 PR 管理系统要求。
|
||||
|
||||
---
|
||||
|
||||
## 🎯 为什么要迁移？
|
||||
|
||||
虽然你的现有 PR **仍将按照当前标准审核和合并**，但将其迁移到新格式可以获得：
|
||||
|
||||
✅ **更快的审核** - 自动化检查尽早捕获问题
|
||||
✅ **更好的反馈** - CI 提供清晰、可操作的反馈
|
||||
✅ **更高质量** - 一致的代码标准
|
||||
✅ **学习机会** - 了解我们新的贡献工作流程
|
||||
|
||||
---
|
||||
|
||||
## ⚡ 快速检查（推荐）
|
||||
|
||||
### 步骤 1：分析你的 PR
|
||||
|
||||
```bash
|
||||
# 运行 PR 健康检查（只读，不修改任何内容）
|
||||
./scripts/pr-check.sh
|
||||
```
|
||||
|
||||
这将分析你的 PR 并告诉你：
|
||||
- ✅ 什么是好的
|
||||
- ⚠️ 什么需要注意
|
||||
- 💡 如何修复问题
|
||||
- 📊 整体健康评分
|
||||
|
||||
### 步骤 2：修复问题
|
||||
|
||||
根据建议，手动修复问题。常见修复：
|
||||
|
||||
```bash
|
||||
# Rebase 到最新 dev
|
||||
git fetch upstream && git rebase upstream/dev
|
||||
|
||||
# 格式化 Go 代码
|
||||
go fmt ./...
|
||||
|
||||
# 运行测试
|
||||
go test ./...
|
||||
|
||||
# 格式化前端代码
|
||||
cd web && npm run lint -- --fix
|
||||
```
|
||||
|
||||
### 步骤 3：再次运行检查
|
||||
|
||||
```bash
|
||||
# 验证所有问题都已修复
|
||||
./scripts/pr-check.sh
|
||||
```
|
||||
|
||||
### 步骤 4：推送更改
|
||||
|
||||
```bash
|
||||
git push -f origin <your-pr-branch>
|
||||
```
|
||||
|
||||
### 脚本做什么
|
||||
|
||||
1. ✅ 与最新的 `upstream/dev` 同步
|
||||
2. ✅ Rebase 你的更改
|
||||
3. ✅ 格式化 Go 代码（`go fmt`）
|
||||
4. ✅ 运行 Go linting（`go vet`）
|
||||
5. ✅ 运行测试
|
||||
6. ✅ 格式化前端代码（如果适用）
|
||||
7. ✅ 推送更改到你的 PR
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 手动迁移（逐步指南）
|
||||
|
||||
如果你更喜欢手动操作：
|
||||
|
||||
### 步骤 1：与 Upstream 同步
|
||||
|
||||
```bash
|
||||
# 如果还没添加 upstream，添加它
|
||||
git remote add upstream https://github.com/tinkle-community/nofx.git
|
||||
|
||||
# 获取最新更改
|
||||
git fetch upstream
|
||||
|
||||
# Rebase 你的分支
|
||||
git checkout <your-pr-branch>
|
||||
git rebase upstream/dev
|
||||
```
|
||||
|
||||
### 步骤 2：后端检查（Go）
|
||||
|
||||
```bash
|
||||
# 格式化 Go 代码
|
||||
go fmt ./...
|
||||
|
||||
# 运行 linting
|
||||
go vet ./...
|
||||
|
||||
# 运行测试
|
||||
go test ./...
|
||||
|
||||
# 如果有更改，提交它们
|
||||
git add .
|
||||
git commit -m "chore: format and fix backend issues"
|
||||
```
|
||||
|
||||
### 步骤 3：前端检查（如果适用）
|
||||
|
||||
```bash
|
||||
cd web
|
||||
|
||||
# 安装依赖
|
||||
npm install
|
||||
|
||||
# 修复 linting 问题
|
||||
npm run lint -- --fix
|
||||
|
||||
# 检查类型
|
||||
npm run type-check
|
||||
|
||||
# 测试构建
|
||||
npm run build
|
||||
|
||||
cd ..
|
||||
|
||||
# 提交任何修复
|
||||
git add .
|
||||
git commit -m "chore: fix frontend issues"
|
||||
```
|
||||
|
||||
### 步骤 4：更新 PR 标题（如果需要）
|
||||
|
||||
确保你的 PR 标题遵循 [Conventional Commits](https://www.conventionalcommits.org/)：
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
示例：
|
||||
feat(exchange): add OKX integration
|
||||
fix(trader): resolve position tracking bug
|
||||
docs(readme): update installation guide
|
||||
```
|
||||
|
||||
**类型：**
|
||||
- `feat` - 新功能
|
||||
- `fix` - Bug 修复
|
||||
- `docs` - 文档
|
||||
- `refactor` - 代码重构
|
||||
- `perf` - 性能改进
|
||||
- `test` - 测试更新
|
||||
- `chore` - 构建/配置更改
|
||||
- `security` - 安全改进
|
||||
|
||||
### 步骤 5：推送更改
|
||||
|
||||
```bash
|
||||
git push -f origin <your-pr-branch>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 检查清单
|
||||
|
||||
迁移后，验证：
|
||||
|
||||
- [ ] PR 已基于最新 `dev` rebase
|
||||
- [ ] 没有合并冲突
|
||||
- [ ] 后端测试在本地通过
|
||||
- [ ] 前端构建成功
|
||||
- [ ] PR 标题遵循 Conventional Commits 格式
|
||||
- [ ] 所有 commit 都有意义
|
||||
- [ ] 更改已推送到 GitHub
|
||||
|
||||
---
|
||||
|
||||
## 🤖 迁移后会发生什么？
|
||||
|
||||
推送更改后：
|
||||
|
||||
1. **自动化检查将运行**（不会阻止合并，只提供反馈）
|
||||
2. **你将收到评论**，包含检查结果和建议
|
||||
3. **维护者将审核** 你的 PR，有了新的上下文
|
||||
4. **更快的审核** 得益于预检查
|
||||
|
||||
---
|
||||
|
||||
## ❓ 故障排除
|
||||
|
||||
### "Rebase 冲突"
|
||||
|
||||
如果在 rebase 期间遇到冲突：
|
||||
|
||||
```bash
|
||||
# 在编辑器中修复冲突
|
||||
# 然后：
|
||||
git add <fixed-files>
|
||||
git rebase --continue
|
||||
|
||||
# 或中止并寻求帮助：
|
||||
git rebase --abort
|
||||
```
|
||||
|
||||
**需要帮助？** 在你的 PR 中评论，我们会协助！
|
||||
|
||||
### "测试失败"
|
||||
|
||||
如果测试失败：
|
||||
|
||||
```bash
|
||||
# 运行测试查看错误
|
||||
go test ./...
|
||||
|
||||
# 修复问题
|
||||
# 然后提交并推送
|
||||
git add .
|
||||
git commit -m "fix: resolve test failures"
|
||||
git push -f origin <your-pr-branch>
|
||||
```
|
||||
|
||||
### "脚本不工作"
|
||||
|
||||
如果迁移脚本不工作：
|
||||
|
||||
1. 检查你是否安装了 Go 和 Node.js
|
||||
2. 尝试手动迁移（上面的步骤）
|
||||
3. 在你的 PR 评论中寻求帮助
|
||||
|
||||
---
|
||||
|
||||
## 💡 提示
|
||||
|
||||
**不想迁移？**
|
||||
- 没关系！你的 PR 仍将被审核和合并
|
||||
- 迁移是可选的但推荐的
|
||||
|
||||
**第一次使用 Git rebase？**
|
||||
- 查看我们的 [Git 指南](https://git-scm.com/book/zh/v2/Git-%E5%88%86%E6%94%AF-%E5%8F%98%E5%9F%BA)
|
||||
- 在你的 PR 中提问 - 我们在这里帮助！
|
||||
|
||||
**想了解更多？**
|
||||
- [贡献指南](../../docs/i18n/zh-CN/CONTRIBUTING.md)
|
||||
- [迁移公告](MIGRATION_ANNOUNCEMENT.zh-CN.md)
|
||||
- [PR 审核指南](../maintainers/PR_REVIEW_GUIDE.zh-CN.md)
|
||||
|
||||
---
|
||||
|
||||
## 📞 需要帮助？
|
||||
|
||||
**迁移遇到困难？**
|
||||
- 在你的 PR 中评论
|
||||
- 在 [Telegram](https://t.me/nofx_dev_community) 提问
|
||||
- 开启 [Discussion](https://github.com/tinkle-community/nofx/discussions)
|
||||
|
||||
**我们在这里帮助你成功！** 🚀
|
||||
|
||||
---
|
||||
|
||||
## 🎉 迁移后
|
||||
|
||||
迁移完成后：
|
||||
1. ✅ 等待自动化检查运行
|
||||
2. ✅ 处理评论中的任何反馈
|
||||
3. ✅ 等待维护者审核
|
||||
4. ✅ 合并时庆祝！🎉
|
||||
|
||||
**感谢你为 NOFX 做出贡献！**
|
||||
358
docs/community/MIGRATION_ANNOUNCEMENT.md
Normal file
358
docs/community/MIGRATION_ANNOUNCEMENT.md
Normal file
@@ -0,0 +1,358 @@
|
||||
# 📢 PR Management System Update - What Contributors Need to Know
|
||||
|
||||
**Language:** [English](MIGRATION_ANNOUNCEMENT.md) | [中文](MIGRATION_ANNOUNCEMENT.zh-CN.md)
|
||||
|
||||
We're introducing a new PR management system to improve code quality and make contributing easier! This guide explains what's changing and what you need to do.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 What's Changing?
|
||||
|
||||
We're introducing:
|
||||
|
||||
✅ **Clear contribution guidelines** aligned with our [roadmap](../roadmap/README.md)
|
||||
✅ **Automated checks** (tests, linting, security scans)
|
||||
✅ **Better labeling** for organization and prioritization
|
||||
✅ **Faster review turnaround** with pre-checks
|
||||
✅ **Transparent process** so you know exactly what to expect
|
||||
|
||||
---
|
||||
|
||||
## 📅 Timeline
|
||||
|
||||
```
|
||||
Week 1-2: Existing PR Review Period
|
||||
Week 3: Soft Launch (checks are advisory only)
|
||||
Week 4+: Full Launch (checks are required)
|
||||
```
|
||||
|
||||
**Important:** This rollout is gradual. You'll have time to adapt!
|
||||
|
||||
---
|
||||
|
||||
## 🤔 What This Means for YOU
|
||||
|
||||
### If You Have an Existing Open PR
|
||||
|
||||
**Good news:** Your PR will NOT be blocked by new rules!
|
||||
|
||||
- ✅ Your PR will be reviewed under current (relaxed) standards
|
||||
- ✅ We'll review and provide feedback within 1-2 weeks
|
||||
- ✅ Some PRs may need a quick rebase or minor updates
|
||||
|
||||
**What you might need to do:**
|
||||
1. **Rebase on latest `dev` branch** if there are conflicts
|
||||
2. **Respond to review comments** within 1 week
|
||||
3. **Be patient** as we work through the backlog
|
||||
|
||||
**What happens if I don't respond?**
|
||||
- We may close your PR after 2 weeks of inactivity
|
||||
- You can always reopen it later with updates!
|
||||
- No hard feelings - we're just cleaning up the backlog
|
||||
|
||||
### 🚀 Want to Check Your PR? (Optional)
|
||||
|
||||
We've created a **PR health check tool** to help you see if your PR meets the new standards!
|
||||
|
||||
**Run this in your local fork:**
|
||||
```bash
|
||||
./scripts/pr-check.sh
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- 🔍 Analyzes your PR (doesn't modify anything)
|
||||
- ✅ Shows what's good
|
||||
- ⚠️ Points out issues
|
||||
- 💡 Gives you specific fix suggestions
|
||||
- 📊 Overall health score
|
||||
|
||||
**Then fix issues and push:**
|
||||
```bash
|
||||
# Fix the issues (see suggestions from script)
|
||||
# Run check again
|
||||
./scripts/pr-check.sh
|
||||
|
||||
# Push when ready
|
||||
git push -f origin <your-branch>
|
||||
```
|
||||
|
||||
**📖 Full Guide:** [How to Migrate Your PR](HOW_TO_MIGRATE_YOUR_PR.md)
|
||||
|
||||
**Remember:** This is completely **optional** for existing PRs!
|
||||
|
||||
---
|
||||
|
||||
### If You're Submitting a NEW PR
|
||||
|
||||
**Timeline matters:**
|
||||
|
||||
#### Week 3 (Soft Launch):
|
||||
- ✅ Automated checks will run (tests, linting, security)
|
||||
- ⚠️ **Checks are advisory only** - they won't block your PR
|
||||
- ✅ This is a learning period - we're here to help!
|
||||
- ✅ Get familiar with the new [Contributing Guidelines](../../CONTRIBUTING.md)
|
||||
|
||||
#### Week 4+ (Full Launch):
|
||||
- ✅ All automated checks must pass before merge
|
||||
- ✅ PR must follow [Conventional Commits](https://www.conventionalcommits.org/) format
|
||||
- ✅ PR template must be filled out
|
||||
- ✅ Must align with [roadmap](../roadmap/README.md) priorities
|
||||
|
||||
---
|
||||
|
||||
## ✅ How to Prepare for New System
|
||||
|
||||
### 1. Read the Contributing Guidelines
|
||||
|
||||
📖 [CONTRIBUTING.md](../../CONTRIBUTING.md)
|
||||
|
||||
**Key points:**
|
||||
- We accept PRs aligned with our roadmap (security, AI, exchanges, UI/UX)
|
||||
- PRs should be focused and small (<300 lines preferred)
|
||||
- Use Conventional Commits format: `feat(area): description`
|
||||
- Include tests for new features
|
||||
|
||||
### 2. Check the Roadmap
|
||||
|
||||
🗺️ [Roadmap](../roadmap/README.md)
|
||||
|
||||
**Current priorities (Phase 1):**
|
||||
- 🔒 Security enhancements
|
||||
- 🧠 AI model integrations
|
||||
- 🔗 Exchange integrations (OKX, Bybit, Lighter, EdgeX)
|
||||
- 🎨 UI/UX improvements
|
||||
- ⚡ Performance optimizations
|
||||
- 🐛 Bug fixes
|
||||
|
||||
**Lower priority (Phase 2+):**
|
||||
- Universal market expansion (stocks, futures)
|
||||
- Advanced AI features
|
||||
- Enterprise features
|
||||
|
||||
💡 **Pro tip:** If your PR aligns with Phase 1, it'll be reviewed faster!
|
||||
|
||||
### 3. Set Up Local Testing
|
||||
|
||||
Before submitting a PR, test locally:
|
||||
|
||||
```bash
|
||||
# Backend tests
|
||||
go test ./...
|
||||
go fmt ./...
|
||||
go vet ./...
|
||||
|
||||
# Frontend tests
|
||||
cd web
|
||||
npm run lint
|
||||
npm run type-check
|
||||
npm run build
|
||||
```
|
||||
|
||||
This helps your PR pass automated checks on first try!
|
||||
|
||||
---
|
||||
|
||||
## 📝 PR Title Format
|
||||
|
||||
Use [Conventional Commits](https://www.conventionalcommits.org/) format:
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
Examples:
|
||||
feat(exchange): add OKX futures support
|
||||
fix(trader): resolve position tracking bug
|
||||
docs(readme): update installation instructions
|
||||
perf(ai): optimize prompt generation
|
||||
```
|
||||
|
||||
**Types:**
|
||||
- `feat` - New feature
|
||||
- `fix` - Bug fix
|
||||
- `docs` - Documentation
|
||||
- `refactor` - Code refactoring
|
||||
- `perf` - Performance improvement
|
||||
- `test` - Test updates
|
||||
- `chore` - Build/config changes
|
||||
- `security` - Security improvements
|
||||
|
||||
---
|
||||
|
||||
## 🎯 What Makes a Good PR?
|
||||
|
||||
### ✅ Good PR Example
|
||||
|
||||
```
|
||||
Title: feat(exchange): add OKX exchange integration
|
||||
|
||||
Description:
|
||||
Implements OKX exchange support with the following features:
|
||||
- Order placement and cancellation
|
||||
- Balance and position retrieval
|
||||
- Leverage configuration
|
||||
- Error handling and retry logic
|
||||
|
||||
Closes #123
|
||||
|
||||
Testing:
|
||||
- [x] Unit tests added and passing
|
||||
- [x] Manually tested with real API
|
||||
- [x] Documentation updated
|
||||
```
|
||||
|
||||
**Why it's good:**
|
||||
- ✅ Clear, descriptive title
|
||||
- ✅ Explains what and why
|
||||
- ✅ Links to issue
|
||||
- ✅ Includes testing details
|
||||
- ✅ Small, focused change
|
||||
|
||||
### ❌ Avoid These
|
||||
|
||||
**Too vague:**
|
||||
```
|
||||
Title: update code
|
||||
Description: made some changes
|
||||
```
|
||||
|
||||
**Too large:**
|
||||
```
|
||||
Title: feat: complete rewrite of entire trading system
|
||||
Files changed: 2,500+
|
||||
```
|
||||
|
||||
**Off roadmap:**
|
||||
```
|
||||
Title: feat: add support for stock trading
|
||||
(This is Phase 3, not current priority)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 If Your PR Fails Checks
|
||||
|
||||
Don't panic! We're here to help.
|
||||
|
||||
**Week 3 (Soft Launch):**
|
||||
- Checks are advisory - we'll help you fix issues
|
||||
- Ask questions in your PR comments
|
||||
- We can guide you through debugging
|
||||
|
||||
**Week 4+ (Full Launch):**
|
||||
- Checks must pass, but we still help!
|
||||
- Common issues:
|
||||
- Test failures → Run `go test ./...` locally
|
||||
- Linting errors → Run `go fmt` and `npm run lint`
|
||||
- Merge conflicts → Rebase on latest `dev`
|
||||
|
||||
**Need help?** Just ask! Comment in your PR or reach out:
|
||||
- [GitHub Discussions](https://github.com/tinkle-community/nofx/discussions)
|
||||
- [Telegram Community](https://t.me/nofx_dev_community)
|
||||
|
||||
---
|
||||
|
||||
## 💰 Special Note for Bounty Contributors
|
||||
|
||||
If you're working on a bounty:
|
||||
|
||||
✅ **Your PRs get priority review** (24-48 hours)
|
||||
✅ **Extra support** to meet requirements
|
||||
✅ **Flexible during transition** - we'll work with you
|
||||
|
||||
Just make sure to:
|
||||
- Reference the bounty issue number
|
||||
- Meet all acceptance criteria
|
||||
- Include demo video/screenshots
|
||||
|
||||
---
|
||||
|
||||
## ❓ FAQ
|
||||
|
||||
### Q: Will my existing PR be rejected?
|
||||
|
||||
**A:** No! Existing PRs use relaxed standards. We may ask for minor updates (rebase, small fixes), but you won't be held to new strict requirements.
|
||||
|
||||
### Q: What if I can't pass the new CI checks?
|
||||
|
||||
**A:** Week 3 is a learning period. We'll help you understand and fix issues. By Week 4, you'll be familiar with the process!
|
||||
|
||||
### Q: Will this slow down contributions?
|
||||
|
||||
**A:** Actually, no! Automated checks catch issues early, making reviews faster. Clear guidelines help you submit better PRs on first try.
|
||||
|
||||
### Q: Can I still contribute if I'm a beginner?
|
||||
|
||||
**A:** Absolutely! Look for issues labeled `good first issue`. We're here to mentor and help you succeed.
|
||||
|
||||
### Q: My PR is large (>1000 lines). What should I do?
|
||||
|
||||
**A:** Consider breaking it into smaller PRs. This gets you:
|
||||
- ✅ Faster reviews
|
||||
- ✅ Easier testing
|
||||
- ✅ Higher chance of quick merge
|
||||
|
||||
Need help planning? Just ask in your PR!
|
||||
|
||||
### Q: What if my feature isn't on the roadmap?
|
||||
|
||||
**A:** Open an issue first to discuss! We're open to good ideas, but want to ensure alignment before you spend time coding.
|
||||
|
||||
### Q: When will this be fully active?
|
||||
|
||||
**A:** Week 4+ (approximately 4 weeks from announcement date). Check the pinned Discussion post for exact dates.
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Benefits for Contributors
|
||||
|
||||
This new system helps YOU by:
|
||||
|
||||
✅ **Faster reviews** - Automated pre-checks reduce review time
|
||||
✅ **Clear expectations** - You know exactly what's required
|
||||
✅ **Better feedback** - Automated checks catch issues early
|
||||
✅ **Fair prioritization** - Roadmap-aligned PRs reviewed faster
|
||||
✅ **Recognition** - Contributor tiers and recognition program
|
||||
|
||||
---
|
||||
|
||||
## 📚 Resources
|
||||
|
||||
### Must Read
|
||||
- [Contributing Guidelines](../../CONTRIBUTING.md) - Complete guide
|
||||
- [Roadmap](../roadmap/README.md) - Current priorities
|
||||
|
||||
### Helpful Links
|
||||
- [Conventional Commits](https://www.conventionalcommits.org/) - Commit format
|
||||
- [Good First Issues](https://github.com/tinkle-community/nofx/labels/good%20first%20issue) - Beginner-friendly tasks
|
||||
- [Bounty Program](../bounty-guide.md) - Get paid to contribute
|
||||
|
||||
### Get Help
|
||||
- [GitHub Discussions](https://github.com/tinkle-community/nofx/discussions) - Ask questions
|
||||
- [Telegram](https://t.me/nofx_dev_community) - Community chat
|
||||
- [Twitter](https://x.com/nofx_ai) - Updates and announcements
|
||||
|
||||
---
|
||||
|
||||
## 💬 Feedback Welcome!
|
||||
|
||||
This is a new system and we want YOUR input:
|
||||
|
||||
- 📝 What's unclear?
|
||||
- 🤔 What concerns do you have?
|
||||
- 💡 How can we improve?
|
||||
|
||||
Share in the [Migration Feedback Discussion](https://github.com/tinkle-community/nofx/discussions) (link TBD)
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Thank You!
|
||||
|
||||
We appreciate your contributions and patience during this transition. Together, we're building something amazing!
|
||||
|
||||
**Questions?** Don't hesitate to ask. We're here to help! 🚀
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-01-XX
|
||||
**Status:** Announcement (Week 0)
|
||||
**Full Launch:** Week 4+ (TBD)
|
||||
358
docs/community/MIGRATION_ANNOUNCEMENT.zh-CN.md
Normal file
358
docs/community/MIGRATION_ANNOUNCEMENT.zh-CN.md
Normal file
@@ -0,0 +1,358 @@
|
||||
# 📢 PR 管理系统更新 - 贡献者须知
|
||||
|
||||
**语言：** [English](MIGRATION_ANNOUNCEMENT.md) | [中文](MIGRATION_ANNOUNCEMENT.zh-CN.md)
|
||||
|
||||
我们正在引入新的 PR 管理系统，以提高代码质量并让贡献变得更容易！本指南解释了变化内容以及你需要做什么。
|
||||
|
||||
---
|
||||
|
||||
## 🎯 有什么变化？
|
||||
|
||||
我们正在引入：
|
||||
|
||||
✅ **清晰的贡献指南** 与我们的[路线图](../roadmap/README.zh-CN.md)对齐
|
||||
✅ **自动化检查**（测试、linting、安全扫描）
|
||||
✅ **更好的标签** 用于组织和优先级排序
|
||||
✅ **更快的审核周转** 通过预检查
|
||||
✅ **透明的流程** 让你准确知道期望什么
|
||||
|
||||
---
|
||||
|
||||
## 📅 时间表
|
||||
|
||||
```
|
||||
第 1-2 周：现有 PR 审核期
|
||||
第 3 周： 软启动（检查仅是建议性的）
|
||||
第 4 周+： 完全启动（检查是必需的）
|
||||
```
|
||||
|
||||
**重要：** 这个推出是渐进式的。你将有时间适应！
|
||||
|
||||
---
|
||||
|
||||
## 🤔 这对你意味着什么
|
||||
|
||||
### 如果你有现有的打开的 PR
|
||||
|
||||
**好消息：** 你的 PR 不会被新规则阻塞！
|
||||
|
||||
- ✅ 你的 PR 将按照当前（宽松）标准进行审核
|
||||
- ✅ 我们将在 1-2 周内审核并提供反馈
|
||||
- ✅ 一些 PR 可能需要快速 rebase 或次要更新
|
||||
|
||||
**你可能需要做什么：**
|
||||
1. **基于最新 `dev` 分支 rebase** 如果有冲突
|
||||
2. **在 1 周内回应审核评论**
|
||||
3. **保持耐心** 我们正在处理积压
|
||||
|
||||
**如果我不回应会怎样？**
|
||||
- 我们可能会在 2 周不活动后关闭你的 PR
|
||||
- 你随时可以稍后重新打开并更新！
|
||||
- 没有恶意 - 我们只是在清理积压
|
||||
|
||||
### 🚀 想要检查你的 PR？（可选）
|
||||
|
||||
我们创建了一个 **PR 健康检查工具**来帮助你看 PR 是否符合新标准！
|
||||
|
||||
**在你的本地 fork 中运行：**
|
||||
```bash
|
||||
./scripts/pr-check.sh
|
||||
```
|
||||
|
||||
**它做什么：**
|
||||
- 🔍 分析你的 PR（不修改任何内容）
|
||||
- ✅ 显示什么是好的
|
||||
- ⚠️ 指出问题
|
||||
- 💡 给你具体的修复建议
|
||||
- 📊 整体健康评分
|
||||
|
||||
**然后修复问题并推送：**
|
||||
```bash
|
||||
# 修复问题（查看脚本的建议）
|
||||
# 再次运行检查
|
||||
./scripts/pr-check.sh
|
||||
|
||||
# 准备好后推送
|
||||
git push -f origin <your-branch>
|
||||
```
|
||||
|
||||
**📖 完整指南：** [如何迁移你的 PR](HOW_TO_MIGRATE_YOUR_PR.zh-CN.md)
|
||||
|
||||
**记住：** 对于现有 PR，这是完全**可选的**！
|
||||
|
||||
---
|
||||
|
||||
### 如果你要提交新的 PR
|
||||
|
||||
**时间很重要：**
|
||||
|
||||
#### 第 3 周（软启动）：
|
||||
- ✅ 自动化检查将运行（测试、linting、安全性）
|
||||
- ⚠️ **检查仅是建议性的** - 不会阻塞你的 PR
|
||||
- ✅ 这是一个学习期 - 我们在这里帮助！
|
||||
- ✅ 熟悉新的[贡献指南](../../docs/i18n/zh-CN/CONTRIBUTING.md)
|
||||
|
||||
#### 第 4 周+（完全启动）：
|
||||
- ✅ 所有自动化检查必须通过才能合并
|
||||
- ✅ PR 必须遵循 [Conventional Commits](https://www.conventionalcommits.org/) 格式
|
||||
- ✅ 必须填写 PR 模板
|
||||
- ✅ 必须与[路线图](../roadmap/README.zh-CN.md)优先级对齐
|
||||
|
||||
---
|
||||
|
||||
## ✅ 如何为新系统做准备
|
||||
|
||||
### 1. 阅读贡献指南
|
||||
|
||||
📖 [CONTRIBUTING.md](../../docs/i18n/zh-CN/CONTRIBUTING.md)
|
||||
|
||||
**关键点：**
|
||||
- 我们接受与路线图对齐的 PR（安全性、AI、交易所、UI/UX）
|
||||
- PR 应该集中且小型（<300 行优先）
|
||||
- 使用 Conventional Commits 格式：`feat(area): description`
|
||||
- 为新功能包含测试
|
||||
|
||||
### 2. 查看路线图
|
||||
|
||||
🗺️ [路线图](../roadmap/README.zh-CN.md)
|
||||
|
||||
**当前优先级（Phase 1）：**
|
||||
- 🔒 安全增强
|
||||
- 🧠 AI 模型集成
|
||||
- 🔗 交易所集成（OKX、Bybit、Lighter、EdgeX）
|
||||
- 🎨 UI/UX 改进
|
||||
- ⚡ 性能优化
|
||||
- 🐛 Bug 修复
|
||||
|
||||
**较低优先级（Phase 2+）：**
|
||||
- 通用市场扩展（股票、期货）
|
||||
- 高级 AI 功能
|
||||
- 企业功能
|
||||
|
||||
💡 **专业提示：** 如果你的 PR 与 Phase 1 对齐，它会被更快审核！
|
||||
|
||||
### 3. 设置本地测试
|
||||
|
||||
提交 PR 前，在本地测试：
|
||||
|
||||
```bash
|
||||
# 后端测试
|
||||
go test ./...
|
||||
go fmt ./...
|
||||
go vet ./...
|
||||
|
||||
# 前端测试
|
||||
cd web
|
||||
npm run lint
|
||||
npm run type-check
|
||||
npm run build
|
||||
```
|
||||
|
||||
这有助于你的 PR 第一次就通过自动化检查！
|
||||
|
||||
---
|
||||
|
||||
## 📝 PR 标题格式
|
||||
|
||||
使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式：
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
示例：
|
||||
feat(exchange): add OKX futures support
|
||||
fix(trader): resolve position tracking bug
|
||||
docs(readme): update installation instructions
|
||||
perf(ai): optimize prompt generation
|
||||
```
|
||||
|
||||
**类型：**
|
||||
- `feat` - 新功能
|
||||
- `fix` - Bug 修复
|
||||
- `docs` - 文档
|
||||
- `refactor` - 代码重构
|
||||
- `perf` - 性能改进
|
||||
- `test` - 测试更新
|
||||
- `chore` - 构建/配置变更
|
||||
- `security` - 安全改进
|
||||
|
||||
---
|
||||
|
||||
## 🎯 什么是好的 PR？
|
||||
|
||||
### ✅ 好的 PR 示例
|
||||
|
||||
```
|
||||
标题：feat(exchange): add OKX exchange integration
|
||||
|
||||
描述：
|
||||
使用以下功能实现 OKX 交易所支持：
|
||||
- 订单下达和取消
|
||||
- 余额和仓位检索
|
||||
- 杠杆配置
|
||||
- 错误处理和重试逻辑
|
||||
|
||||
关闭 #123
|
||||
|
||||
测试：
|
||||
- [x] 单元测试已添加并通过
|
||||
- [x] 使用真实 API 手动测试
|
||||
- [x] 文档已更新
|
||||
```
|
||||
|
||||
**为什么好：**
|
||||
- ✅ 清晰、描述性标题
|
||||
- ✅ 解释了什么和为什么
|
||||
- ✅ 链接到 issue
|
||||
- ✅ 包含测试详情
|
||||
- ✅ 小型、集中的变更
|
||||
|
||||
### ❌ 避免这些
|
||||
|
||||
**太模糊：**
|
||||
```
|
||||
标题：update code
|
||||
描述：made some changes
|
||||
```
|
||||
|
||||
**太大：**
|
||||
```
|
||||
标题：feat: complete rewrite of entire trading system
|
||||
文件变更：2,500+
|
||||
```
|
||||
|
||||
**不在路线图上：**
|
||||
```
|
||||
标题：feat: add support for stock trading
|
||||
（这是 Phase 3，不是当前优先级）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 如果你的 PR 检查失败
|
||||
|
||||
不要恐慌！我们在这里帮助。
|
||||
|
||||
**第 3 周（软启动）：**
|
||||
- 检查是建议性的 - 我们会帮你解决问题
|
||||
- 在你的 PR 评论中提问
|
||||
- 我们可以指导你进行调试
|
||||
|
||||
**第 4 周+（完全启动）：**
|
||||
- 检查必须通过，但我们仍然会帮助！
|
||||
- 常见问题：
|
||||
- 测试失败 → 在本地运行 `go test ./...`
|
||||
- Linting 错误 → 运行 `go fmt` 和 `npm run lint`
|
||||
- 合并冲突 → 基于最新 `dev` rebase
|
||||
|
||||
**需要帮助？** 只管问！在你的 PR 中评论或联系：
|
||||
- [GitHub Discussions](https://github.com/tinkle-community/nofx/discussions)
|
||||
- [Telegram 社区](https://t.me/nofx_dev_community)
|
||||
|
||||
---
|
||||
|
||||
## 💰 悬赏贡献者特别说明
|
||||
|
||||
如果你正在做悬赏任务：
|
||||
|
||||
✅ **你的 PR 获得优先审核**（24-48 小时）
|
||||
✅ **额外支持** 以满足要求
|
||||
✅ **过渡期间灵活** - 我们会与你合作
|
||||
|
||||
只需确保：
|
||||
- 引用悬赏 issue 编号
|
||||
- 满足所有验收标准
|
||||
- 包含演示视频/截图
|
||||
|
||||
---
|
||||
|
||||
## ❓ 常见问题
|
||||
|
||||
### Q：我的现有 PR 会被拒绝吗？
|
||||
|
||||
**A：** 不会！现有 PR 使用宽松标准。我们可能会要求次要更新（rebase、小修复），但你不会被要求满足新的严格要求。
|
||||
|
||||
### Q：如果我无法通过新的 CI 检查怎么办？
|
||||
|
||||
**A：** 第 3 周是学习期。我们会帮你理解和修复问题。到第 4 周，你将熟悉这个流程！
|
||||
|
||||
### Q：这会减慢贡献速度吗？
|
||||
|
||||
**A：** 实际上不会！自动化检查尽早捕获问题，使审核更快。清晰的指南帮助你第一次就提交更好的 PR。
|
||||
|
||||
### Q：如果我是初学者，我还能贡献吗？
|
||||
|
||||
**A：** 绝对可以！查找标记为 `good first issue` 的 issue。我们在这里指导并帮助你成功。
|
||||
|
||||
### Q：我的 PR 很大（>1000 行）。我应该怎么做？
|
||||
|
||||
**A：** 考虑将其拆分为更小的 PR。这让你获得：
|
||||
- ✅ 更快的审核
|
||||
- ✅ 更容易的测试
|
||||
- ✅ 更高的快速合并机会
|
||||
|
||||
需要帮助规划？在你的 PR 中提问即可！
|
||||
|
||||
### Q：如果我的功能不在路线图上怎么办？
|
||||
|
||||
**A：** 先开一个 issue 讨论！我们对好想法持开放态度，但在你花时间编码之前想确保对齐。
|
||||
|
||||
### Q：这将何时完全激活？
|
||||
|
||||
**A：** 第 4 周+（从公告日期起大约 4 周）。查看置顶的 Discussion 帖子了解确切日期。
|
||||
|
||||
---
|
||||
|
||||
## 🎉 对贡献者的好处
|
||||
|
||||
这个新系统通过以下方式帮助你：
|
||||
|
||||
✅ **更快的审核** - 自动化预检查减少审核时间
|
||||
✅ **清晰的期望** - 你准确知道需要什么
|
||||
✅ **更好的反馈** - 自动化检查尽早捕获问题
|
||||
✅ **公平的优先级排序** - 路线图对齐的 PR 审核更快
|
||||
✅ **表彰** - 贡献者等级和表彰计划
|
||||
|
||||
---
|
||||
|
||||
## 📚 资源
|
||||
|
||||
### 必读
|
||||
- [贡献指南](../../docs/i18n/zh-CN/CONTRIBUTING.md) - 完整指南
|
||||
- [路线图](../roadmap/README.zh-CN.md) - 当前优先级
|
||||
|
||||
### 有用链接
|
||||
- [Conventional Commits](https://www.conventionalcommits.org/) - Commit 格式
|
||||
- [Good First Issues](https://github.com/tinkle-community/nofx/labels/good%20first%20issue) - 适合初学者的任务
|
||||
- [悬赏计划](../bounty-guide.md) - 获得报酬来贡献
|
||||
|
||||
### 获取帮助
|
||||
- [GitHub Discussions](https://github.com/tinkle-community/nofx/discussions) - 提问
|
||||
- [Telegram](https://t.me/nofx_dev_community) - 社区聊天
|
||||
- [Twitter](https://x.com/nofx_ai) - 更新和公告
|
||||
|
||||
---
|
||||
|
||||
## 💬 欢迎反馈！
|
||||
|
||||
这是一个新系统，我们想要你的意见：
|
||||
|
||||
- 📝 什么不清楚？
|
||||
- 🤔 你有什么顾虑？
|
||||
- 💡 我们如何改进？
|
||||
|
||||
在[迁移反馈讨论](https://github.com/tinkle-community/nofx/discussions)中分享（链接待定）
|
||||
|
||||
---
|
||||
|
||||
## 🙏 谢谢你！
|
||||
|
||||
我们感谢你的贡献和在这次过渡期间的耐心。我们一起正在构建令人惊叹的东西！
|
||||
|
||||
**问题？** 不要犹豫提问。我们在这里帮助！🚀
|
||||
|
||||
---
|
||||
|
||||
**最后更新：** 2025-01-XX
|
||||
**状态：** 公告（第 0 周）
|
||||
**完全启动：** 第 4 周+（待定）
|
||||
173
docs/community/PR_COMMENT_TEMPLATE.md
Normal file
173
docs/community/PR_COMMENT_TEMPLATE.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# 📢 PR Comment Template for Existing PRs
|
||||
|
||||
This template is for maintainers to comment on existing PRs to introduce the new system.
|
||||
|
||||
---
|
||||
|
||||
## Template (English)
|
||||
|
||||
```markdown
|
||||
Hi @{username}! 👋
|
||||
|
||||
Thank you for your contribution to NOFX!
|
||||
|
||||
## 🚀 New PR Management System
|
||||
|
||||
We're introducing a new PR management system to improve code quality and make reviews faster. Your PR will **not be blocked** by these changes - we'll review it under current standards.
|
||||
|
||||
### ✨ Optional: Want to check your PR against new standards?
|
||||
|
||||
We've created a **PR health check tool** that analyzes your PR and gives you suggestions!
|
||||
|
||||
**How to use:**
|
||||
|
||||
```bash
|
||||
# In your local fork, on your PR branch
|
||||
cd /path/to/your/nofx-fork
|
||||
git checkout <your-branch-name>
|
||||
|
||||
# Run the health check (reads only, doesn't modify)
|
||||
./scripts/pr-check.sh
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- 🔍 Analyzes your PR (doesn't modify anything)
|
||||
- ✅ Shows what's already good
|
||||
- ⚠️ Points out issues
|
||||
- 💡 Gives specific suggestions on how to fix
|
||||
- 📊 Overall health score
|
||||
|
||||
**Then fix and re-check:**
|
||||
```bash
|
||||
# Fix the issues based on suggestions
|
||||
# Run check again to verify
|
||||
./scripts/pr-check.sh
|
||||
|
||||
# Push when everything looks good
|
||||
git push origin <your-branch-name>
|
||||
```
|
||||
|
||||
### 📖 Learn More
|
||||
|
||||
- [Migration Announcement](https://github.com/tinkle-community/nofx/blob/dev/docs/community/MIGRATION_ANNOUNCEMENT.md)
|
||||
- [Contributing Guidelines](https://github.com/tinkle-community/nofx/blob/dev/CONTRIBUTING.md)
|
||||
|
||||
### ❓ Questions?
|
||||
|
||||
Just ask here! We're happy to help. 🙏
|
||||
|
||||
---
|
||||
|
||||
**Note:** This migration is **completely optional** for existing PRs. We'll review and merge your PR either way!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template (Chinese / 中文)
|
||||
|
||||
```markdown
|
||||
嗨 @{username}！👋
|
||||
|
||||
感谢你为 NOFX 做出的贡献！
|
||||
|
||||
## 🚀 新的 PR 管理系统
|
||||
|
||||
我们正在引入新的 PR 管理系统，以提高代码质量并加快审核速度。你的 PR **不会被阻止** - 我们将按照当前标准审核它。
|
||||
|
||||
### ✨ 可选：想要检查你的 PR 吗？
|
||||
|
||||
我们创建了一个 **PR 健康检查工具**来帮助你看 PR 是否符合新标准！
|
||||
|
||||
**在你的本地 fork 中运行：**
|
||||
|
||||
```bash
|
||||
# 在你的本地 fork 中，切换到你的 PR 分支
|
||||
cd /path/to/your/nofx-fork
|
||||
git checkout <your-branch-name>
|
||||
|
||||
# 运行健康检查（只读，不修改任何内容）
|
||||
./scripts/pr-check.sh
|
||||
```
|
||||
|
||||
**它做什么：**
|
||||
- 🔍 分析你的 PR（不修改任何内容）
|
||||
- ✅ 显示什么是好的
|
||||
- ⚠️ 指出问题
|
||||
- 💡 给你具体的修复建议
|
||||
- 📊 整体健康评分
|
||||
|
||||
**然后修复问题并推送：**
|
||||
```bash
|
||||
# 修复问题（查看脚本的建议）
|
||||
# 再次运行检查
|
||||
./scripts/pr-check.sh
|
||||
|
||||
# 准备好后推送
|
||||
git push origin <your-branch-name>
|
||||
```
|
||||
|
||||
### 📖 了解更多
|
||||
|
||||
- [迁移公告](https://github.com/tinkle-community/nofx/blob/dev/docs/community/MIGRATION_ANNOUNCEMENT.zh-CN.md)
|
||||
- [贡献指南](https://github.com/tinkle-community/nofx/blob/dev/docs/i18n/zh-CN/CONTRIBUTING.md)
|
||||
|
||||
### ❓ 问题？
|
||||
|
||||
在这里提问即可！我们很乐意帮助。🙏
|
||||
|
||||
---
|
||||
|
||||
**注意：** 对于现有 PR，此迁移是**完全可选的**。无论如何我们都会审核和合并你的 PR！
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Copy-Paste Template
|
||||
|
||||
For quick commenting on multiple PRs:
|
||||
|
||||
```markdown
|
||||
👋 Hi! Thanks for your PR!
|
||||
|
||||
We're introducing a new PR system. Your PR won't be blocked - we'll review it normally.
|
||||
|
||||
**Want to check your PR?** Run this in your fork:
|
||||
```bash
|
||||
./scripts/pr-check.sh
|
||||
```
|
||||
|
||||
[Learn more](https://github.com/tinkle-community/nofx/blob/dev/docs/community/MIGRATION_ANNOUNCEMENT.md) | This is optional!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Bulk Comment Script (for maintainers)
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# Comment on all open PRs
|
||||
gh pr list --state open --json number --jq '.[].number' | while read pr_number; do
|
||||
echo "Commenting on PR #$pr_number"
|
||||
|
||||
gh pr comment "$pr_number" --body "👋 Hi! Thanks for your PR!
|
||||
|
||||
We're introducing a new PR system. Your PR won't be blocked - we'll review it normally.
|
||||
|
||||
**Want to check your PR?** Run this in your fork:
|
||||
\`\`\`bash
|
||||
./scripts/pr-check.sh
|
||||
\`\`\`
|
||||
|
||||
[Learn more](https://github.com/tinkle-community/nofx/blob/dev/docs/community/MIGRATION_ANNOUNCEMENT.md) | This is optional!"
|
||||
|
||||
echo "✅ Commented on PR #$pr_number"
|
||||
sleep 2 # Be nice to GitHub API
|
||||
done
|
||||
```
|
||||
|
||||
Save as `comment-all-prs.sh` and run:
|
||||
```bash
|
||||
chmod +x comment-all-prs.sh
|
||||
./comment-all-prs.sh
|
||||
```
|
||||
@@ -4,6 +4,20 @@ Welcome to the NOFX community! This section contains everything you need to cont
|
||||
|
||||
---
|
||||
|
||||
## 📢 Important Announcement
|
||||
|
||||
**🚀 New PR Management System Coming Soon!**
|
||||
|
||||
We're introducing a new PR management system to improve code quality and make contributing easier!
|
||||
|
||||
**📖 Read:** [Migration Announcement](MIGRATION_ANNOUNCEMENT.md) | [迁移公告（中文）](MIGRATION_ANNOUNCEMENT.zh-CN.md)
|
||||
|
||||
**Timeline:** 4-week gradual rollout starting soon
|
||||
|
||||
**For existing PRs:** Don't worry! Your PRs will not be blocked by new rules.
|
||||
|
||||
---
|
||||
|
||||
## 🤝 How to Contribute
|
||||
|
||||
### Getting Started
|
||||
|
||||
481
docs/i18n/zh-CN/CONTRIBUTING.md
Normal file
481
docs/i18n/zh-CN/CONTRIBUTING.md
Normal file
@@ -0,0 +1,481 @@
|
||||
# 🤝 为 NOFX 做贡献
|
||||
|
||||
**语言：** [English](../../../CONTRIBUTING.md) | [中文](CONTRIBUTING.md)
|
||||
|
||||
感谢您有兴趣为 NOFX 做贡献！本文档提供了为项目做贡献的指南和工作流程。
|
||||
|
||||
---
|
||||
|
||||
## 📑 目录
|
||||
|
||||
- [行为准则](#行为准则)
|
||||
- [如何贡献](#如何贡献)
|
||||
- [开发工作流程](#开发工作流程)
|
||||
- [PR 提交指南](#pr-提交指南)
|
||||
- [编码规范](#编码规范)
|
||||
- [提交信息指南](#提交信息指南)
|
||||
- [审核流程](#审核流程)
|
||||
- [悬赏计划](#悬赏计划)
|
||||
|
||||
---
|
||||
|
||||
## 📜 行为准则
|
||||
|
||||
本项目遵守[行为准则](../../../CODE_OF_CONDUCT.md)。参与项目即表示您同意遵守此准则。
|
||||
|
||||
---
|
||||
|
||||
## 🎯 如何贡献
|
||||
|
||||
### 1. 报告 Bug 🐛
|
||||
|
||||
- 使用 [Bug 报告模板](../../../.github/ISSUE_TEMPLATE/bug_report.md)
|
||||
- 检查 bug 是否已被报告
|
||||
- 包含详细的重现步骤
|
||||
- 提供环境信息（操作系统、Go 版本等）
|
||||
|
||||
### 2. 建议功能 ✨
|
||||
|
||||
- 使用[功能请求模板](../../../.github/ISSUE_TEMPLATE/feature_request.md)
|
||||
- 解释使用场景和好处
|
||||
- 检查是否与[项目路线图](../../roadmap/README.zh-CN.md)一致
|
||||
|
||||
### 3. 提交 Pull Request 🔧
|
||||
|
||||
提交 PR 前，请检查以下内容：
|
||||
|
||||
#### ✅ **接受的贡献**
|
||||
|
||||
**高优先级**（与路线图一致）：
|
||||
- 🔒 安全增强（加密、认证、RBAC）
|
||||
- 🧠 AI 模型集成（GPT-4、Claude、Gemini Pro）
|
||||
- 🔗 交易所集成（OKX、Bybit、Lighter、EdgeX）
|
||||
- 📊 交易数据 API（AI500、OI 分析、NetFlow）
|
||||
- 🎨 UI/UX 改进（移动端响应式、图表）
|
||||
- ⚡ 性能优化
|
||||
- 🐛 Bug 修复
|
||||
- 📝 文档改进
|
||||
|
||||
**中等优先级：**
|
||||
- ✅ 测试覆盖率改进
|
||||
- 🌐 国际化（新语言支持）
|
||||
- 🔧 构建/部署工具
|
||||
- 📈 监控和日志增强
|
||||
|
||||
#### ❌ **不接受**（未经事先讨论）
|
||||
|
||||
- 没有 RFC（征求意见稿）的重大架构变更
|
||||
- 与项目路线图不一致的功能
|
||||
- 没有迁移路径的破坏性变更
|
||||
- 引入新依赖但没有充分理由的代码
|
||||
- 没有可选标志的实验性功能
|
||||
|
||||
**⚠️ 重要：** 对于重大功能，请在开始工作**之前**先开 issue 讨论。
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 开发工作流程
|
||||
|
||||
### 1. Fork 和 Clone
|
||||
|
||||
```bash
|
||||
# 在 GitHub 上 Fork 仓库
|
||||
# 然后 clone 你的 fork
|
||||
git clone https://github.com/YOUR_USERNAME/nofx.git
|
||||
cd nofx
|
||||
|
||||
# 添加 upstream remote
|
||||
git remote add upstream https://github.com/tinkle-community/nofx.git
|
||||
```
|
||||
|
||||
### 2. 创建功能分支
|
||||
|
||||
```bash
|
||||
# 更新你的本地 dev 分支
|
||||
git checkout dev
|
||||
git pull upstream dev
|
||||
|
||||
# 创建新分支
|
||||
git checkout -b feature/your-feature-name
|
||||
# 或
|
||||
git checkout -b fix/your-bug-fix
|
||||
```
|
||||
|
||||
**分支命名规范：**
|
||||
- `feature/` - 新功能
|
||||
- `fix/` - Bug 修复
|
||||
- `docs/` - 文档更新
|
||||
- `refactor/` - 代码重构
|
||||
- `perf/` - 性能改进
|
||||
- `test/` - 测试更新
|
||||
- `chore/` - 构建/配置更改
|
||||
|
||||
### 3. 设置开发环境
|
||||
|
||||
```bash
|
||||
# 安装 Go 依赖
|
||||
go mod download
|
||||
|
||||
# 安装前端依赖
|
||||
cd web
|
||||
npm install
|
||||
cd ..
|
||||
|
||||
# 安装 TA-Lib（必需）
|
||||
# macOS:
|
||||
brew install ta-lib
|
||||
|
||||
# Ubuntu/Debian:
|
||||
sudo apt-get install libta-lib0-dev
|
||||
```
|
||||
|
||||
### 4. 进行更改
|
||||
|
||||
- 遵循[编码规范](#编码规范)
|
||||
- 为新功能编写测试
|
||||
- 根据需要更新文档
|
||||
- 保持提交专注和原子性
|
||||
|
||||
### 5. 测试你的更改
|
||||
|
||||
```bash
|
||||
# 运行后端测试
|
||||
go test ./...
|
||||
|
||||
# 构建后端
|
||||
go build -o nofx
|
||||
|
||||
# 以开发模式运行前端
|
||||
cd web
|
||||
npm run dev
|
||||
|
||||
# 构建前端
|
||||
npm run build
|
||||
```
|
||||
|
||||
### 6. 提交你的更改
|
||||
|
||||
遵循[提交信息指南](#提交信息指南)：
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat: add support for OKX exchange integration"
|
||||
```
|
||||
|
||||
### 7. 推送并创建 PR
|
||||
|
||||
```bash
|
||||
# 推送到你的 fork
|
||||
git push origin feature/your-feature-name
|
||||
|
||||
# 前往 GitHub 创建 Pull Request
|
||||
# 使用 PR 模板并填写所有部分
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 PR 提交指南
|
||||
|
||||
### 提交前检查
|
||||
|
||||
- [ ] 代码成功编译（`go build` 和 `npm run build`）
|
||||
- [ ] 所有测试通过（`go test ./...`）
|
||||
- [ ] 没有 linting 错误（`go fmt`、`go vet`）
|
||||
- [ ] 文档已更新
|
||||
- [ ] 提交遵循 conventional commits 格式
|
||||
- [ ] 分支已基于最新的 `dev` rebase
|
||||
|
||||
### PR 标题格式
|
||||
|
||||
使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式：
|
||||
|
||||
```
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
示例：
|
||||
feat(exchange): add OKX exchange integration
|
||||
fix(trader): resolve position tracking bug
|
||||
docs(readme): update installation instructions
|
||||
perf(ai): optimize prompt generation
|
||||
refactor(core): extract common exchange interface
|
||||
```
|
||||
|
||||
**类型：**
|
||||
- `feat` - 新功能
|
||||
- `fix` - Bug 修复
|
||||
- `docs` - 文档
|
||||
- `style` - 代码样式（格式化，无逻辑变更）
|
||||
- `refactor` - 代码重构
|
||||
- `perf` - 性能改进
|
||||
- `test` - 测试更新
|
||||
- `chore` - 构建/配置更改
|
||||
- `ci` - CI/CD 更改
|
||||
- `security` - 安全改进
|
||||
|
||||
### PR 描述
|
||||
|
||||
使用 [PR 模板](../../../.github/PULL_REQUEST_TEMPLATE.md)并确保：
|
||||
|
||||
1. **清晰描述**更改内容和原因
|
||||
2. **变更类型**已标记
|
||||
3. **相关 issue** 已链接
|
||||
4. **测试步骤**已记录
|
||||
5. UI 更改有**截图**
|
||||
6. **所有复选框**已完成
|
||||
|
||||
### PR 大小
|
||||
|
||||
保持 PR 专注且大小合理：
|
||||
|
||||
- ✅ **小型 PR**（< 300 行）：理想，审核快速
|
||||
- ⚠️ **中型 PR**（300-1000 行）：可接受，可能需要更长时间
|
||||
- ❌ **大型 PR**（> 1000 行）：请拆分为更小的 PR
|
||||
|
||||
---
|
||||
|
||||
## 💻 编码规范
|
||||
|
||||
### Go 代码
|
||||
|
||||
```go
|
||||
// ✅ 好：清晰的命名，正确的错误处理
|
||||
func ConnectToExchange(apiKey, secret string) (*Exchange, error) {
|
||||
if apiKey == "" || secret == "" {
|
||||
return nil, fmt.Errorf("API credentials are required")
|
||||
}
|
||||
|
||||
client, err := createClient(apiKey, secret)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("failed to create client: %w", err)
|
||||
}
|
||||
|
||||
return &Exchange{client: client}, nil
|
||||
}
|
||||
|
||||
// ❌ 差：糟糕的命名，没有错误处理
|
||||
func ce(a, s string) *Exchange {
|
||||
c := createClient(a, s)
|
||||
return &Exchange{client: c}
|
||||
}
|
||||
```
|
||||
|
||||
**最佳实践：**
|
||||
- 使用有意义的变量名
|
||||
- 显式处理所有错误
|
||||
- 为复杂逻辑添加注释
|
||||
- 遵循 Go 习惯用法和约定
|
||||
- 提交前运行 `go fmt`
|
||||
- 使用 `go vet` 和 `golangci-lint`
|
||||
|
||||
### TypeScript/React 代码
|
||||
|
||||
```typescript
|
||||
// ✅ 好：类型安全，清晰的命名
|
||||
interface TraderConfig {
|
||||
id: string;
|
||||
exchange: 'binance' | 'hyperliquid' | 'aster';
|
||||
aiModel: string;
|
||||
enabled: boolean;
|
||||
}
|
||||
|
||||
const TraderCard: React.FC<{ trader: TraderConfig }> = ({ trader }) => {
|
||||
const [isRunning, setIsRunning] = useState(false);
|
||||
|
||||
const handleStart = async () => {
|
||||
try {
|
||||
await startTrader(trader.id);
|
||||
setIsRunning(true);
|
||||
} catch (error) {
|
||||
console.error('Failed to start trader:', error);
|
||||
}
|
||||
};
|
||||
|
||||
return <div>...</div>;
|
||||
};
|
||||
|
||||
// ❌ 差：没有类型，不清晰的命名
|
||||
const TC = (props) => {
|
||||
const [r, setR] = useState(false);
|
||||
const h = () => { startTrader(props.t.id); setR(true); };
|
||||
return <div>...</div>;
|
||||
};
|
||||
```
|
||||
|
||||
**最佳实践：**
|
||||
- 使用 TypeScript 严格模式
|
||||
- 为所有数据结构定义接口
|
||||
- 避免使用 `any` 类型
|
||||
- 使用带 hooks 的函数式组件
|
||||
- 遵循 React 最佳实践
|
||||
- 提交前运行 `npm run lint`
|
||||
|
||||
### 文件结构
|
||||
|
||||
```
|
||||
NOFX/
|
||||
├── cmd/ # 主应用程序
|
||||
├── internal/ # 私有代码
|
||||
│ ├── exchange/ # 交易所适配器
|
||||
│ ├── trader/ # 交易逻辑
|
||||
│ ├── ai/ # AI 集成
|
||||
│ └── api/ # API 处理器
|
||||
├── pkg/ # 公共库
|
||||
├── web/ # 前端
|
||||
│ ├── src/
|
||||
│ │ ├── components/
|
||||
│ │ ├── pages/
|
||||
│ │ ├── hooks/
|
||||
│ │ └── utils/
|
||||
│ └── public/
|
||||
└── docs/ # 文档
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 提交信息指南
|
||||
|
||||
### 格式
|
||||
|
||||
```
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
|
||||
<footer>
|
||||
```
|
||||
|
||||
### 示例
|
||||
|
||||
```
|
||||
feat(exchange): add OKX futures API integration
|
||||
|
||||
- Implement order placement and cancellation
|
||||
- Add balance and position retrieval
|
||||
- Support leverage configuration
|
||||
|
||||
Closes #123
|
||||
```
|
||||
|
||||
```
|
||||
fix(trader): prevent duplicate position opening
|
||||
|
||||
The trader was opening multiple positions in the same direction
|
||||
for the same symbol. Added check to prevent this behavior.
|
||||
|
||||
Fixes #456
|
||||
```
|
||||
|
||||
```
|
||||
docs: update Docker deployment guide
|
||||
|
||||
- Add troubleshooting section
|
||||
- Update environment variables
|
||||
- Add examples for common scenarios
|
||||
```
|
||||
|
||||
### 规则
|
||||
|
||||
- 使用现在时（"add" 而非 "added"）
|
||||
- 使用祈使语气（"move" 而非 "moves"）
|
||||
- 第一行 ≤ 72 字符
|
||||
- 引用 issue 和 PR
|
||||
- 解释"是什么"和"为什么"，而非"如何做"
|
||||
|
||||
---
|
||||
|
||||
## 🔍 审核流程
|
||||
|
||||
### 时间线
|
||||
|
||||
- **初次审核：** 2-3 个工作日内
|
||||
- **后续审核：** 1-2 个工作日内
|
||||
- **悬赏 PR：** 1 个工作日内优先审核
|
||||
|
||||
### 审核标准
|
||||
|
||||
审核者将检查：
|
||||
|
||||
1. **功能性**
|
||||
- 是否按预期工作？
|
||||
- 边界情况是否处理？
|
||||
- 现有功能没有退化？
|
||||
|
||||
2. **代码质量**
|
||||
- 遵循编码规范？
|
||||
- 结构良好且可读？
|
||||
- 正确的错误处理？
|
||||
|
||||
3. **测试**
|
||||
- 测试覆盖率足够？
|
||||
- CI 中测试通过？
|
||||
- 手动测试已记录？
|
||||
|
||||
4. **文档**
|
||||
- 需要的地方有代码注释？
|
||||
- README/文档已更新？
|
||||
- API 变更已记录？
|
||||
|
||||
5. **安全性**
|
||||
- 没有硬编码的密钥？
|
||||
- 输入验证？
|
||||
- 没有已知漏洞？
|
||||
|
||||
### 回应反馈
|
||||
|
||||
- 处理所有审核评论
|
||||
- 不清楚时提问
|
||||
- 标记对话为已解决
|
||||
- 更改后重新请求审核
|
||||
|
||||
### 批准和合并
|
||||
|
||||
- 需要维护者 **1 个批准**
|
||||
- 所有 CI 检查必须通过
|
||||
- 没有未解决的对话
|
||||
- 维护者将合并（小型 PR 使用 squash merge，功能使用 merge commit）
|
||||
|
||||
---
|
||||
|
||||
## 💰 悬赏计划
|
||||
|
||||
### 工作方式
|
||||
|
||||
1. 查看[悬赏 issue](https://github.com/tinkle-community/nofx/labels/bounty)
|
||||
2. 评论认领（先到先得）
|
||||
3. 在截止日期前完成工作
|
||||
4. 提交 PR 并填写悬赏认领部分
|
||||
5. 合并后获得报酬
|
||||
|
||||
### 指南
|
||||
|
||||
- 阅读[悬赏指南](../../community/bounty-guide.md)
|
||||
- 满足所有验收标准
|
||||
- 包含演示视频/截图
|
||||
- 遵循所有贡献指南
|
||||
- 私下讨论付款详情
|
||||
|
||||
---
|
||||
|
||||
## ❓ 问题？
|
||||
|
||||
- **一般问题：** 加入我们的 [Telegram 社区](https://t.me/nofx_dev_community)
|
||||
- **技术问题：** 开启[讨论](https://github.com/tinkle-community/nofx/discussions)
|
||||
- **安全问题：** 查看[安全政策](../../../SECURITY.md)
|
||||
- **Bug 报告：** 使用 [Bug 报告模板](../../../.github/ISSUE_TEMPLATE/bug_report.md)
|
||||
|
||||
---
|
||||
|
||||
## 📚 其他资源
|
||||
|
||||
- [项目路线图](../../roadmap/README.zh-CN.md)
|
||||
- [架构文档](../../architecture/README.zh-CN.md)
|
||||
- [API 文档](../../api/README.md)
|
||||
- [部署指南](../../getting-started/docker-deploy.zh-CN.md)
|
||||
|
||||
---
|
||||
|
||||
## 🙏 感谢你！
|
||||
|
||||
你的贡献让 NOFX 变得更好。我们感谢你的时间和努力！
|
||||
|
||||
**编码愉快！🚀**
|
||||
398
docs/maintainers/PROJECT_MANAGEMENT.md
Normal file
398
docs/maintainers/PROJECT_MANAGEMENT.md
Normal 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
398
docs/maintainers/PROJECT_MANAGEMENT.zh-CN.md
Normal 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
458
docs/maintainers/PR_REVIEW_GUIDE.md
Normal 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
457
docs/maintainers/PR_REVIEW_GUIDE.zh-CN.md
Normal 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
51
docs/maintainers/README.md
Normal 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
51
docs/maintainers/README.zh-CN.md
Normal 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
381
docs/maintainers/SETUP_GUIDE.md
Normal 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
381
docs/maintainers/SETUP_GUIDE.zh-CN.md
Normal 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 管理系统现在已准备好：
|
||||
|
||||
✅ 用清晰的指南引导贡献者
|
||||
✅ 自动化重复任务
|
||||
✅ 保持代码质量
|
||||
✅ 系统性地跟踪进度
|
||||
✅ 扩展社区
|
||||
|
||||
**有问题？** 在维护者频道联系我们或开启讨论。
|
||||
|
||||
**让我们构建令人惊叹的社区！🚀**
|
||||
Reference in New Issue
Block a user