open-git/nofx
1
0
Fork 0
mirror of https://github.com/NoFxAiOS/nofx.git synced 2025-12-06 13:54:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: pr validation

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

127
.github/labeler.yml vendored Normal file
View File

@@ -0,0 +1,127 @@
# Auto-labeler configuration
# Automatically adds labels based on changed files
# Area: Frontend
'area: frontend':
- changed-files:
- any-glob-to-any-file:
- 'web/**/*'
- '*.tsx'
- '*.ts'
- '*.jsx'
- '*.js'
- '*.css'
# Area: Backend
'area: backend':
- changed-files:
- any-glob-to-any-file:
- '**/*.go'
- 'go.mod'
- 'go.sum'
- 'cmd/**/*'
- 'internal/**/*'
- 'pkg/**/*'
# Area: Exchange
'area: exchange':
- changed-files:
- any-glob-to-any-file:
- 'internal/exchange/**/*'
- 'pkg/exchange/**/*'
- '**/binance*.go'
- '**/hyperliquid*.go'
- '**/aster*.go'
- '**/okx*.go'
- '**/bybit*.go'
# Area: AI
'area: ai':
- changed-files:
- any-glob-to-any-file:
- 'internal/ai/**/*'
- 'pkg/ai/**/*'
- '**/deepseek*.go'
- '**/qwen*.go'
- '**/openai*.go'
- '**/claude*.go'
# Area: API
'area: api':
- changed-files:
- any-glob-to-any-file:
- 'internal/api/**/*'
- 'pkg/api/**/*'
- '**/handler*.go'
- '**/router*.go'
# Area: Security
'area: security':
- changed-files:
- any-glob-to-any-file:
- '**/auth*.go'
- '**/jwt*.go'
- '**/encryption*.go'
- '**/crypto*.go'
- 'SECURITY.md'
# Area: Database
'area: database':
- changed-files:
- any-glob-to-any-file:
- 'internal/database/**/*'
- 'internal/db/**/*'
- '**/migration*.go'
- '**/*.sql'
- '**/schema*.go'
# Area: UI/UX
'area: ui/ux':
- changed-files:
- any-glob-to-any-file:
- 'web/src/components/**/*'
- 'web/src/pages/**/*'
- '**/*.css'
- '**/style*.ts'
# Area: Deployment
'area: deployment':
- changed-files:
- any-glob-to-any-file:
- 'Dockerfile'
- 'docker-compose*.yml'
- '.github/workflows/**/*'
- 'start.sh'
- '**/*deploy*.md'
# Type: Documentation
'type: documentation':
- changed-files:
- any-glob-to-any-file:
- 'docs/**/*'
- '*.md'
- 'README*'
- 'CHANGELOG*'
- 'CONTRIBUTING.md'
- 'CODE_OF_CONDUCT.md'
# Type: Test
'type: test':
- changed-files:
- any-glob-to-any-file:
- '**/*_test.go'
- 'test/**/*'
- '**/*.test.ts'
- '**/*.test.tsx'
- '**/*.spec.ts'
# Dependencies
'dependencies':
- changed-files:
- any-glob-to-any-file:
- 'go.mod'
- 'go.sum'
- 'package.json'
- 'package-lock.json'
- 'web/package.json'
- 'web/package-lock.json'

180
.github/labels.yml vendored Normal file
View File

@@ -0,0 +1,180 @@
# GitHub Labels Configuration
# Use https://github.com/crazy-max/ghaction-github-labeler to sync labels
# Priority Labels
- name: "priority: critical"
color: "d73a4a"
description: "Critical priority - requires immediate attention"
- name: "priority: high"
color: "ff6b6b"
description: "High priority - should be addressed soon"
- name: "priority: medium"
color: "fbca04"
description: "Medium priority - normal queue"
- name: "priority: low"
color: "0e8a16"
description: "Low priority - nice to have"
# Type Labels
- name: "type: bug"
color: "d73a4a"
description: "Something isn't working"
- name: "type: feature"
color: "a2eeef"
description: "New feature or request"
- name: "type: enhancement"
color: "84b6eb"
description: "Improvement to existing feature"
- name: "type: documentation"
color: "0075ca"
description: "Documentation improvements"
- name: "type: security"
color: "ee0701"
description: "Security-related changes"
- name: "type: performance"
color: "f9d0c4"
description: "Performance improvements"
- name: "type: refactor"
color: "fbca04"
description: "Code refactoring"
- name: "type: test"
color: "c5def5"
description: "Test-related changes"
# Status Labels
- name: "status: needs review"
color: "fbca04"
description: "PR is ready for review"
- name: "status: needs changes"
color: "d93f0b"
description: "PR needs changes based on review"
- name: "status: on hold"
color: "fef2c0"
description: "PR/issue is on hold"
- name: "status: in progress"
color: "0e8a16"
description: "Currently being worked on"
- name: "status: blocked"
color: "d93f0b"
description: "Blocked by another issue/PR"
# Area Labels (aligned with roadmap)
- name: "area: security"
color: "ee0701"
description: "Security enhancements (Phase 1.1)"
- name: "area: ai"
color: "7057ff"
description: "AI capabilities and models (Phase 1.2)"
- name: "area: exchange"
color: "0075ca"
description: "Exchange integrations (Phase 1.3)"
- name: "area: architecture"
color: "d4c5f9"
description: "Project structure refactoring (Phase 1.4)"
- name: "area: ui/ux"
color: "c2e0c6"
description: "User experience improvements (Phase 1.5)"
- name: "area: frontend"
color: "bfdadc"
description: "Frontend (React/TypeScript)"
- name: "area: backend"
color: "c5def5"
description: "Backend (Go)"
- name: "area: api"
color: "0e8a16"
description: "API endpoints"
- name: "area: database"
color: "f9d0c4"
description: "Database changes"
- name: "area: deployment"
color: "fbca04"
description: "Deployment and CI/CD"
# Special Labels
- name: "good first issue"
color: "7057ff"
description: "Good for newcomers"
- name: "help wanted"
color: "008672"
description: "Extra attention is needed"
- name: "bounty"
color: "1d76db"
description: "Bounty available for this issue"
- name: "bounty: claimed"
color: "5319e7"
description: "Bounty has been claimed"
- name: "bounty: paid"
color: "0e8a16"
description: "Bounty has been paid"
- name: "RFC"
color: "d4c5f9"
description: "Request for Comments - needs discussion"
- name: "breaking change"
color: "d73a4a"
description: "Includes breaking changes"
- name: "duplicate"
color: "cfd3d7"
description: "This issue or pull request already exists"
- name: "invalid"
color: "e4e669"
description: "This doesn't seem right"
- name: "wontfix"
color: "ffffff"
description: "This will not be worked on"
- name: "dependencies"
color: "0366d6"
description: "Dependency updates"
# Roadmap Phases
- name: "roadmap: phase-1"
color: "0e8a16"
description: "Core Infrastructure Enhancement"
- name: "roadmap: phase-2"
color: "fbca04"
description: "Testing & Stability"
- name: "roadmap: phase-3"
color: "0075ca"
description: "Universal Market Expansion"
- name: "roadmap: phase-4"
color: "7057ff"
description: "Advanced AI & Automation"
- name: "roadmap: phase-5"
color: "d73a4a"
description: "Enterprise & Scaling"

331
.github/workflows/pr-checks-advisory.yml vendored Normal file
View File

@@ -0,0 +1,331 @@
name: PR Checks (Advisory)
on:
pull_request:
types: [opened, synchronize, reopened]
branches: [main, dev]
# These checks are advisory only - they won't block PR merging
# Results will be posted as comments to help contributors improve their PRs
jobs:
pr-info:
name: PR Information
runs-on: ubuntu-latest
permissions:
pull-requests: write
steps:
- name: Check PR title format
id: check-title
run: |
PR_TITLE="${{ github.event.pull_request.title }}"
# Check if title follows conventional commits
if echo "$PR_TITLE" | grep -qE "^(feat|fix|docs|style|refactor|perf|test|chore|ci|security)(\(.+\))?: .+"; then
echo "status=✅ Good" >> $GITHUB_OUTPUT
echo "message=PR title follows Conventional Commits format" >> $GITHUB_OUTPUT
else
echo "status=⚠️ Suggestion" >> $GITHUB_OUTPUT
echo "message=Consider using Conventional Commits format: type(scope): description" >> $GITHUB_OUTPUT
fi
- name: Calculate PR size
id: pr-size
run: |
ADDITIONS=${{ github.event.pull_request.additions }}
DELETIONS=${{ github.event.pull_request.deletions }}
TOTAL=$((ADDITIONS + DELETIONS))
if [ $TOTAL -lt 100 ]; then
echo "size=🟢 Small" >> $GITHUB_OUTPUT
echo "label=size: small" >> $GITHUB_OUTPUT
elif [ $TOTAL -lt 500 ]; then
echo "size=🟡 Medium" >> $GITHUB_OUTPUT
echo "label=size: medium" >> $GITHUB_OUTPUT
else
echo "size=🔴 Large" >> $GITHUB_OUTPUT
echo "label=size: large" >> $GITHUB_OUTPUT
echo "suggestion=Consider breaking this into smaller PRs for easier review" >> $GITHUB_OUTPUT
fi
echo "lines=$TOTAL" >> $GITHUB_OUTPUT
- name: Post advisory comment
uses: actions/github-script@v7
with:
script: |
const titleStatus = '${{ steps.check-title.outputs.status }}';
const titleMessage = '${{ steps.check-title.outputs.message }}';
const prSize = '${{ steps.pr-size.outputs.size }}';
const prLines = '${{ steps.pr-size.outputs.lines }}';
const sizeSuggestion = '${{ steps.pr-size.outputs.suggestion }}' || '';
let comment = '## 🤖 PR Advisory Feedback\n\n';
comment += 'Thank you for your contribution! Here\'s some automated feedback to help improve your PR:\n\n';
comment += '### PR Title\n';
comment += titleStatus + ' ' + titleMessage + '\n\n';
comment += '### PR Size\n';
comment += prSize + ' (' + prLines + ' lines changed)\n';
if (sizeSuggestion) {
comment += '\n💡 **Suggestion:** ' + sizeSuggestion + '\n';
}
comment += '\n---\n\n';
comment += '### 📖 New PR Management System\n\n';
comment += 'We\'re introducing a new PR management system! These checks are **advisory only** and won\'t block your PR.\n\n';
comment += '**Want to check your PR against new standards?**\n';
comment += '```bash\n';
comment += '# Run the PR health check tool\n';
comment += './scripts/pr-check.sh\n';
comment += '```\n\n';
comment += 'This tool will:\n';
comment += '- 🔍 Analyze your PR (doesn\'t modify anything)\n';
comment += '- ✅ Show what\'s already good\n';
comment += '- ⚠️ Point out issues\n';
comment += '- 💡 Give specific suggestions on how to fix\n\n';
comment += '**Learn more:**\n';
comment += '- [Migration Guide](https://github.com/tinkle-community/nofx/blob/dev/docs/community/MIGRATION_ANNOUNCEMENT.md)\n';
comment += '- [Contributing Guidelines](https://github.com/tinkle-community/nofx/blob/dev/CONTRIBUTING.md)\n\n';
comment += '**Questions?** Just ask in the comments! We\'re here to help. 🙏\n\n';
comment += '---\n\n';
comment += '*This is an automated message. It won\'t affect your PR being merged.*';
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: comment
});
backend-checks:
name: Backend Checks (Advisory)
runs-on: ubuntu-latest
permissions:
pull-requests: write
continue-on-error: true
steps:
- uses: actions/checkout@v4
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: '1.21'
- name: Install dependencies
run: |
sudo apt-get update
sudo apt-get install -y libta-lib-dev || true
go mod download || true
- name: Check Go formatting
id: go-fmt
continue-on-error: true
run: |
UNFORMATTED=$(gofmt -l . 2>/dev/null || echo "")
if [ -n "$UNFORMATTED" ]; then
echo "status=⚠️ Needs formatting" >> $GITHUB_OUTPUT
echo "files<<EOF" >> $GITHUB_OUTPUT
echo "$UNFORMATTED" | head -10 >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
else
echo "status=✅ Good" >> $GITHUB_OUTPUT
echo "files=" >> $GITHUB_OUTPUT
fi
- name: Run go vet
id: go-vet
continue-on-error: true
run: |
if go vet ./... 2>&1 | tee vet-output.txt; then
echo "status=✅ Good" >> $GITHUB_OUTPUT
echo "output=" >> $GITHUB_OUTPUT
else
echo "status=⚠️ Issues found" >> $GITHUB_OUTPUT
echo "output<<EOF" >> $GITHUB_OUTPUT
cat vet-output.txt | head -20 >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
fi
- name: Run tests
id: go-test
continue-on-error: true
run: |
if go test ./... -v 2>&1 | tee test-output.txt; then
echo "status=✅ Passed" >> $GITHUB_OUTPUT
echo "output=" >> $GITHUB_OUTPUT
else
echo "status=⚠️ Failed" >> $GITHUB_OUTPUT
echo "output<<EOF" >> $GITHUB_OUTPUT
cat test-output.txt | tail -30 >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
fi
- name: Post backend feedback
if: always()
uses: actions/github-script@v7
with:
script: |
const fmtStatus = '${{ steps.go-fmt.outputs.status }}' || '⚠️ Skipped';
const vetStatus = '${{ steps.go-vet.outputs.status }}' || '⚠️ Skipped';
const testStatus = '${{ steps.go-test.outputs.status }}' || '⚠️ Skipped';
const fmtFiles = `${{ steps.go-fmt.outputs.files }}`;
const vetOutput = `${{ steps.go-vet.outputs.output }}`;
const testOutput = `${{ steps.go-test.outputs.output }}`;
let comment = '## 🔧 Backend Checks (Advisory)\n\n';
comment += '### Go Formatting\n';
comment += fmtStatus + '\n';
if (fmtFiles) {
comment += '\nFiles needing formatting:\n```\n' + fmtFiles + '\n```\n';
}
comment += '\n### Go Vet\n';
comment += vetStatus + '\n';
if (vetOutput) {
comment += '\n```\n' + vetOutput.substring(0, 500) + '\n```\n';
}
comment += '\n### Tests\n';
comment += testStatus + '\n';
if (testOutput) {
comment += '\n```\n' + testOutput.substring(0, 1000) + '\n```\n';
}
comment += '\n---\n\n';
comment += '💡 **To fix locally:**\n';
comment += '```bash\n';
comment += '# Format code\n';
comment += 'go fmt ./...\n\n';
comment += '# Check for issues\n';
comment += 'go vet ./...\n\n';
comment += '# Run tests\n';
comment += 'go test ./...\n';
comment += '```\n\n';
comment += '*These checks are advisory and won\'t block merging. Need help? Just ask!*';
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: comment
});
frontend-checks:
name: Frontend Checks (Advisory)
runs-on: ubuntu-latest
permissions:
pull-requests: write
continue-on-error: true
steps:
- uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
- name: Check if web directory exists
id: check-web
run: |
if [ -d "web" ]; then
echo "exists=true" >> $GITHUB_OUTPUT
else
echo "exists=false" >> $GITHUB_OUTPUT
fi
- name: Install dependencies
if: steps.check-web.outputs.exists == 'true'
working-directory: ./web
continue-on-error: true
run: npm ci
- name: Run linter
if: steps.check-web.outputs.exists == 'true'
id: lint
working-directory: ./web
continue-on-error: true
run: |
if npm run lint 2>&1 | tee lint-output.txt; then
echo "status=✅ Good" >> $GITHUB_OUTPUT
echo "output=" >> $GITHUB_OUTPUT
else
echo "status=⚠️ Issues found" >> $GITHUB_OUTPUT
echo "output<<EOF" >> $GITHUB_OUTPUT
cat lint-output.txt | head -20 >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
fi
- name: Type check
if: steps.check-web.outputs.exists == 'true'
id: typecheck
working-directory: ./web
continue-on-error: true
run: |
if npm run type-check 2>&1 | tee typecheck-output.txt; then
echo "status=✅ Good" >> $GITHUB_OUTPUT
echo "output=" >> $GITHUB_OUTPUT
else
echo "status=⚠️ Issues found" >> $GITHUB_OUTPUT
echo "output<<EOF" >> $GITHUB_OUTPUT
cat typecheck-output.txt | head -20 >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
fi
- name: Build
if: steps.check-web.outputs.exists == 'true'
id: build
working-directory: ./web
continue-on-error: true
run: |
if npm run build 2>&1 | tee build-output.txt; then
echo "status=✅ Success" >> $GITHUB_OUTPUT
echo "output=" >> $GITHUB_OUTPUT
else
echo "status=⚠️ Failed" >> $GITHUB_OUTPUT
echo "output<<EOF" >> $GITHUB_OUTPUT
cat build-output.txt | tail -20 >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
fi
- name: Post frontend feedback
if: always() && steps.check-web.outputs.exists == 'true'
uses: actions/github-script@v7
with:
script: |
const lintStatus = '${{ steps.lint.outputs.status }}' || '⚠️ Skipped';
const typecheckStatus = '${{ steps.typecheck.outputs.status }}' || '⚠️ Skipped';
const buildStatus = '${{ steps.build.outputs.status }}' || '⚠️ Skipped';
const lintOutput = `${{ steps.lint.outputs.output }}`;
const typecheckOutput = `${{ steps.typecheck.outputs.output }}`;
const buildOutput = `${{ steps.build.outputs.output }}`;
let comment = '## ⚛️ Frontend Checks (Advisory)\n\n';
comment += '### Linting\n';
comment += lintStatus + '\n';
if (lintOutput) {
comment += '\n```\n' + lintOutput.substring(0, 500) + '\n```\n';
}
comment += '\n### Type Checking\n';
comment += typecheckStatus + '\n';
if (typecheckOutput) {
comment += '\n```\n' + typecheckOutput.substring(0, 500) + '\n```\n';
}
comment += '\n### Build\n';
comment += buildStatus + '\n';
if (buildOutput) {
comment += '\n```\n' + buildOutput.substring(0, 500) + '\n```\n';
}
comment += '\n---\n\n';
comment += '💡 **To fix locally:**\n';
comment += '```bash\n';
comment += 'cd web\n\n';
comment += '# Fix linting issues\n';
comment += 'npm run lint -- --fix\n\n';
comment += '# Check types\n';
comment += 'npm run type-check\n\n';
comment += '# Test build\n';
comment += 'npm run build\n';
comment += '```\n\n';
comment += '*These checks are advisory and won\'t block merging. Need help? Just ask!*';
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: comment
});

237
.github/workflows/pr-checks.yml vendored Normal file
View File

@@ -0,0 +1,237 @@
name: PR Checks
on:
pull_request:
types: [opened, synchronize, reopened, edited]
branches:
- dev
- main
jobs:
# Validate PR title and description
validate-pr:
name: Validate PR Format
runs-on: ubuntu-latest
steps:
- name: Check PR title format
uses: amannn/action-semantic-pull-request@v5
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
types: |
feat
fix
docs
style
refactor
perf
test
chore
ci
security
scopes: |
exchange
trader
ai
api
ui
frontend
backend
security
deps
requireScope: false
- name: Check PR size
uses: actions/github-script@v7
with:
script: |
const pr = context.payload.pull_request;
const additions = pr.additions;
const deletions = pr.deletions;
const total = additions + deletions;
let label = '';
let comment = '';
if (total < 300) {
label = 'size: small';
comment = '✅ This PR is **small** and easy to review!';
} else if (total < 1000) {
label = 'size: medium';
comment = '⚠️ This PR is **medium** sized. Consider breaking it into smaller PRs if possible.';
} else {
label = 'size: large';
comment = '🚨 This PR is **large** (>' + total + ' lines changed). Please consider breaking it into smaller, focused PRs for easier review.';
}
// Add size label
await github.rest.issues.addLabels({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: pr.number,
labels: [label]
});
// Add comment for large PRs
if (total >= 1000) {
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: pr.number,
body: comment
});
}
# Backend tests
backend-tests:
name: Backend Tests (Go)
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: '1.21'
- name: Install TA-Lib
run: |
sudo apt-get update
sudo apt-get install -y libta-lib-dev
- name: Cache Go modules
uses: actions/cache@v4
with:
path: ~/go/pkg/mod
key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
restore-keys: |
${{ runner.os }}-go-
- name: Download dependencies
run: go mod download
- name: Run go fmt
run: |
if [ "$(gofmt -s -l . | wc -l)" -gt 0 ]; then
echo "Please run 'go fmt' on your code"
gofmt -s -l .
exit 1
fi
- name: Run go vet
run: go vet ./...
- name: Run tests
run: go test -v -race -coverprofile=coverage.out ./...
- name: Build
run: go build -v -o nofx
- name: Upload coverage
uses: codecov/codecov-action@v4
with:
file: ./coverage.out
flags: backend
# Frontend tests
frontend-tests:
name: Frontend Tests (React/TypeScript)
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
- name: Cache Node modules
uses: actions/cache@v4
with:
path: web/node_modules
key: ${{ runner.os }}-node-${{ hashFiles('web/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
- name: Install dependencies
working-directory: ./web
run: npm ci
- name: Run linter
working-directory: ./web
run: npm run lint
- name: Run type check
working-directory: ./web
run: npm run type-check || true # Don't fail on type errors for now
- name: Build
working-directory: ./web
run: npm run build
# Auto-label based on files changed
auto-label:
name: Auto Label PR
runs-on: ubuntu-latest
permissions:
pull-requests: write
steps:
- uses: actions/labeler@v5
with:
configuration-path: .github/labeler.yml
repo-token: ${{ secrets.GITHUB_TOKEN }}
# Check for security issues
security-check:
name: Security Scan
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Run Trivy vulnerability scanner
uses: aquasecurity/trivy-action@master
with:
scan-type: 'fs'
scan-ref: '.'
format: 'sarif'
output: 'trivy-results.sarif'
- name: Upload Trivy results
uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: 'trivy-results.sarif'
# Check for secrets in code
secrets-check:
name: Check for Secrets
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run Gitleaks
uses: gitleaks/gitleaks-action@v2
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# All checks passed
all-checks:
name: All Checks Passed
runs-on: ubuntu-latest
needs: [validate-pr, backend-tests, frontend-tests, security-check, secrets-check]
if: always()
steps:
- name: Check all jobs
run: |
if [ "${{ contains(needs.*.result, 'failure') }}" == "true" ]; then
echo "Some checks failed"
exit 1
else
echo "All checks passed!"
fi

481
CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,481 @@
# 🤝 Contributing to NOFX
**Language:** [English](CONTRIBUTING.md) | [中文](docs/i18n/zh-CN/CONTRIBUTING.md)
Thank you for your interest in contributing to NOFX! This document provides guidelines and workflows for contributing to the project.
---
## 📑 Table of Contents
- [Code of Conduct](#code-of-conduct)
- [How Can I Contribute?](#how-can-i-contribute)
- [Development Workflow](#development-workflow)
- [PR Submission Guidelines](#pr-submission-guidelines)
- [Coding Standards](#coding-standards)
- [Commit Message Guidelines](#commit-message-guidelines)
- [Review Process](#review-process)
- [Bounty Program](#bounty-program)
---
## 📜 Code of Conduct
This project adheres to the [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
---
## 🎯 How Can I Contribute?
### 1. Report Bugs 🐛
- Use the [Bug Report Template](.github/ISSUE_TEMPLATE/bug_report.md)
- Check if the bug has already been reported
- Include detailed reproduction steps
- Provide environment information (OS, Go version, etc.)
### 2. Suggest Features ✨
- Use the [Feature Request Template](.github/ISSUE_TEMPLATE/feature_request.md)
- Explain the use case and benefits
- Check if it aligns with the [project roadmap](docs/roadmap/README.md)
### 3. Submit Pull Requests 🔧
Before submitting a PR, please check the following:
#### ✅ **Accepted Contributions**
**High Priority** (aligned with roadmap):
- 🔒 Security enhancements (encryption, authentication, RBAC)
- 🧠 AI model integrations (GPT-4, Claude, Gemini Pro)
- 🔗 Exchange integrations (OKX, Bybit, Lighter, EdgeX)
- 📊 Trading data APIs (AI500, OI analysis, NetFlow)
- 🎨 UI/UX improvements (mobile responsiveness, charts)
- ⚡ Performance optimizations
- 🐛 Bug fixes
- 📝 Documentation improvements
**Medium Priority:**
- ✅ Test coverage improvements
- 🌐 Internationalization (new language support)
- 🔧 Build/deployment tooling
- 📈 Monitoring and logging enhancements
#### ❌ **Not Accepted** (without prior discussion)
- Major architectural changes without RFC (Request for Comments)
- Features not aligned with project roadmap
- Breaking changes without migration path
- Code that introduces new dependencies without justification
- Experimental features without opt-in flag
**⚠️ Important:** For major features, please open an issue for discussion **before** starting work.
---
## 🛠️ Development Workflow
### 1. Fork and Clone
```bash
# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/nofx.git
cd nofx
# Add upstream remote
git remote add upstream https://github.com/tinkle-community/nofx.git
```
### 2. Create a Feature Branch
```bash
# Update your local dev branch
git checkout dev
git pull upstream dev
# Create a new branch
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
```
**Branch Naming Convention:**
- `feature/` - New features
- `fix/` - Bug fixes
- `docs/` - Documentation updates
- `refactor/` - Code refactoring
- `perf/` - Performance improvements
- `test/` - Test updates
- `chore/` - Build/config changes
### 3. Set Up Development Environment
```bash
# Install Go dependencies
go mod download
# Install frontend dependencies
cd web
npm install
cd ..
# Install TA-Lib (required)
# macOS:
brew install ta-lib
# Ubuntu/Debian:
sudo apt-get install libta-lib0-dev
```
### 4. Make Your Changes
- Follow the [coding standards](#coding-standards)
- Write tests for new features
- Update documentation as needed
- Keep commits focused and atomic
### 5. Test Your Changes
```bash
# Run backend tests
go test ./...
# Build backend
go build -o nofx
# Run frontend in dev mode
cd web
npm run dev
# Build frontend
npm run build
```
### 6. Commit Your Changes
Follow the [commit message guidelines](#commit-message-guidelines):
```bash
git add .
git commit -m "feat: add support for OKX exchange integration"
```
### 7. Push and Create PR
```bash
# Push to your fork
git push origin feature/your-feature-name
# Go to GitHub and create a Pull Request
# Use the PR template and fill in all sections
```
---
## 📝 PR Submission Guidelines
### Before Submitting
- [ ] Code compiles successfully (`go build` and `npm run build`)
- [ ] All tests pass (`go test ./...`)
- [ ] No linting errors (`go fmt`, `go vet`)
- [ ] Documentation is updated
- [ ] Commits follow conventional commits format
- [ ] Branch is rebased on latest `dev`
### PR Title Format
Use [Conventional Commits](https://www.conventionalcommits.org/) format:
```
<type>(<scope>): <subject>
Examples:
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
```
**Types:**
- `feat` - New feature
- `fix` - Bug fix
- `docs` - Documentation
- `style` - Code style (formatting, no logic change)
- `refactor` - Code refactoring
- `perf` - Performance improvement
- `test` - Test updates
- `chore` - Build/config changes
- `ci` - CI/CD changes
- `security` - Security improvements
### PR Description
Use the [PR template](.github/PULL_REQUEST_TEMPLATE.md) and ensure:
1. **Clear description** of what and why
2. **Type of change** is marked
3. **Related issues** are linked
4. **Testing steps** are documented
5. **Screenshots** for UI changes
6. **All checkboxes** are completed
### PR Size
Keep PRs focused and reasonably sized:
- ✅ **Small PR** (< 300 lines): Ideal, fast review
- ⚠️ **Medium PR** (300-1000 lines): Acceptable, may take longer
- ❌ **Large PR** (> 1000 lines): Please break into smaller PRs
---
## 💻 Coding Standards
### Go Code
```go
// ✅ Good: Clear naming, proper error handling
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
}
// ❌ Bad: Poor naming, no error handling
func ce(a, s string) *Exchange {
c := createClient(a, s)
return &Exchange{client: c}
}
```
**Best Practices:**
- Use meaningful variable names
- Handle all errors explicitly
- Add comments for complex logic
- Follow Go idioms and conventions
- Run `go fmt` before committing
- Use `go vet` and `golangci-lint`
### TypeScript/React Code
```typescript
// ✅ Good: Type-safe, clear naming
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>;
};
// ❌ Bad: No types, unclear naming
const TC = (props) => {
const [r, setR] = useState(false);
const h = () => { startTrader(props.t.id); setR(true); };
return <div>...</div>;
};
```
**Best Practices:**
- Use TypeScript strict mode
- Define interfaces for all data structures
- Avoid `any` type
- Use functional components with hooks
- Follow React best practices
- Run `npm run lint` before committing
### File Structure
```
NOFX/
├── cmd/ # Main applications
├── internal/ # Private code
│ ├── exchange/ # Exchange adapters
│ ├── trader/ # Trading logic
│ ├── ai/ # AI integrations
│ └── api/ # API handlers
├── pkg/ # Public libraries
├── web/ # Frontend
│ ├── src/
│ │ ├── components/
│ │ ├── pages/
│ │ ├── hooks/
│ │ └── utils/
│ └── public/
└── docs/ # Documentation
```
---
## 📋 Commit Message Guidelines
### Format
```
<type>(<scope>): <subject>
<body>
<footer>
```
### Examples
```
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
```
### Rules
- Use present tense ("add" not "added")
- Use imperative mood ("move" not "moves")
- First line ≤ 72 characters
- Reference issues and PRs
- Explain "what" and "why", not "how"
---
## 🔍 Review Process
### Timeline
- **Initial review:** Within 2-3 business days
- **Follow-up reviews:** Within 1-2 business days
- **Bounty PRs:** Priority review within 1 business day
### Review Criteria
Reviewers will check:
1. **Functionality**
- Does it work as intended?
- Are edge cases handled?
- No regression in existing features?
2. **Code Quality**
- Follows coding standards?
- Well-structured and readable?
- Proper error handling?
3. **Testing**
- Adequate test coverage?
- Tests pass in CI?
- Manual testing documented?
4. **Documentation**
- Code comments where needed?
- README/docs updated?
- API changes documented?
5. **Security**
- No hardcoded secrets?
- Input validation?
- No known vulnerabilities?
### Response to Feedback
- Address all review comments
- Ask questions if unclear
- Mark conversations as resolved
- Re-request review after changes
### Approval and Merge
- Requires **1 approval** from maintainers
- All CI checks must pass
- No unresolved conversations
- Maintainers will merge (squash merge for small PRs, merge commit for features)
---
## 💰 Bounty Program
### How It Works
1. Check [open bounty issues](https://github.com/tinkle-community/nofx/labels/bounty)
2. Comment to claim (first come, first served)
3. Complete work within deadline
4. Submit PR with bounty claim section filled
5. Get paid upon merge
### Guidelines
- Read [Bounty Guide](docs/community/bounty-guide.md)
- Meet all acceptance criteria
- Include demo video/screenshots
- Follow all contribution guidelines
- Payment details discussed privately
---
## ❓ Questions?
- **General questions:** Join our [Telegram Community](https://t.me/nofx_dev_community)
- **Technical questions:** Open a [Discussion](https://github.com/tinkle-community/nofx/discussions)
- **Security issues:** See [Security Policy](SECURITY.md)
- **Bug reports:** Use [Bug Report Template](.github/ISSUE_TEMPLATE/bug_report.md)
---
## 📚 Additional Resources
- [Project Roadmap](docs/roadmap/README.md)
- [Architecture Documentation](docs/architecture/README.md)
- [API Documentation](docs/api/README.md)
- [Deployment Guide](docs/getting-started/docker-deploy.en.md)
---
## 🙏 Thank You!
Your contributions make NOFX better for everyone. We appreciate your time and effort!
**Happy coding! 🚀**

272
docs/community/HOW_TO_MIGRATE_YOUR_PR.md Normal file
View 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
View 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
View 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
View 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
View 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
```

14
docs/community/README.md
View File

@@ -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
View 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
View File

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,381 @@
# 🚀 PR 管理系统设置指南
**语言：** [English](SETUP_GUIDE.md) | [中文](SETUP_GUIDE.zh-CN.md)
本指南将帮助你为 NOFX 设置和激活完整的 PR 管理系统。
---
## 📦 包含内容
PR 管理系统包括：
### 1. **文档**
- ✅ `CONTRIBUTING.md` - 贡献者指南
- ✅ `docs/maintainers/PR_REVIEW_GUIDE.md` - 审核者指南
- ✅ `docs/maintainers/PROJECT_MANAGEMENT.md` - 项目管理工作流程
- ✅ `docs/maintainers/SETUP_GUIDE.md` - 本文件
### 2. **GitHub 配置**
- ✅ `.github/PULL_REQUEST_TEMPLATE.md` - PR 模板（已存在）
- ✅ `.github/labels.yml` - 标签定义
- ✅ `.github/labeler.yml` - 自动标签规则
- ✅ `.github/workflows/pr-checks.yml` - 自动化 PR 检查
### 3. **自动化**
- ✅ 自动 PR 标签
- ✅ PR 大小检查
- ✅ CI/CD 测试
- ✅ 安全扫描
- ✅ Commit 信息验证
---
## 🔧 设置步骤
### 步骤 1：同步 GitHub 标签
创建 `.github/labels.yml` 中定义的标签：
```bash
# 选项 1：使用 gh CLI（推荐）
gh label list # 查看当前标签
gh label delete <label-name> # 如需要，删除旧标签
gh label create "priority: critical" --color "d73a4a" --description "Critical priority"
# ... 为 labels.yml 中的所有标签重复
# 选项 2：使用 GitHub Labeler Action（自动化）
# 工作流将在推送时自动同步标签
```
**或使用 GitHub Labeler Action**（添加到 `.github/workflows/sync-labels.yml`）：
```yaml
name: Sync Labels
on:
push:
branches: [main, dev]
paths:
- '.github/labels.yml'
jobs:
labels:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: crazy-max/ghaction-github-labeler@v5
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
yaml-file: .github/labels.yml
```
### 步骤 2：启用 GitHub Actions
1. 前往 **Settings → Actions → General**
2. 启用 **"Allow all actions and reusable workflows"**
3. 设置 **Workflow permissions** 为 **"Read and write permissions"**
4. 勾选 **"Allow GitHub Actions to create and approve pull requests"**
### 步骤 3：设置分支保护规则
**对于 `main` 分支：**
1. 前往 **Settings → Branches → Add rule**
2. 分支名称模式：`main`
3. 配置：
- ✅ Require a pull request before merging
- ✅ Require approvals: **1**
- ✅ Require status checks to pass before merging
- 选择：`Backend Tests (Go)`
- 选择：`Frontend Tests (React/TypeScript)`
- 选择：`Security Scan`
- ✅ Require conversation resolution before merging
- ✅ Do not allow bypassing the above settings
- ❌ Allow force pushes（禁用）
- ❌ Allow deletions（禁用）
**对于 `dev` 分支：**
1. 与上面相同，但：
- Require approvals: **1**
- 宽松一些（如需要允许维护者绕过）
### 步骤 4：创建 GitHub Projects
1. 前往 **Projects → New project**
2. 创建 **"NOFX Development"** 看板
- 模板：Board
- 添加列：`Backlog`、`Triaged`、`In Progress`、`In Review`、`Done`
- 添加视图：Sprint、Roadmap、By Area、Priority
3. 创建 **"Bounty Program"** 看板
- 模板：Board
- 添加列：`Available`、`Claimed`、`In Progress`、`Under Review`、`Paid`
### 步骤 5：启用 Discussions（可选但推荐）
1. 前往 **Settings → General → Features**
2. 启用 **"Discussions"**
3. 创建分类：
- 💬 **General** - 一般讨论
- 💡 **Ideas** - 功能想法和建议
- 🙏 **Q&A** - 问答
- 📢 **Announcements** - 重要更新
- 🗳️ **Polls** - 社区投票
### 步骤 6：配置 Issue 模板
模板已存在于 `.github/ISSUE_TEMPLATE/` 中。验证它们是否正常工作：
1. 前往 **Issues → New issue**
2. 你应该看到：
- 🐛 Bug Report
- ✨ Feature Request
- 💰 Bounty Claim
如果没有显示，检查文件是否为正确格式的 YAML 和 frontmatter。
### 步骤 7：设置 Code Owners（可选）
创建 `.github/CODEOWNERS`：
```
# 全局所有者
* @tinkle @zack
# 前端
/web/ @frontend-lead
# 交易所集成
/internal/exchange/ @exchange-lead
# AI 组件
/internal/ai/ @ai-lead
# 文档
/docs/ @tinkle @zack
*.md @tinkle @zack
```
### 步骤 8：配置通知
**对于维护者：**
1. 前往 **Settings → Notifications**
2. 启用：
- ✅ Pull request reviews
- ✅ Pull request pushes
- ✅ Comments on issues and PRs
- ✅ New issues
- ✅ Security alerts
3. 设置电子邮件过滤器来组织通知
**对于仓库：**
1. 前往 **Settings → Webhooks**（如果与 Slack/Discord 集成）
2. 添加通知 webhook
---
## 📋 设置后检查清单
设置后，验证：
- [ ] 标签已创建并可见
- [ ] 分支保护规则已激活
- [ ] GitHub Actions 工作流在新 PR 上运行
- [ ] 自动标签工作（创建测试 PR）
- [ ] 创建 PR 时显示 PR 模板
- [ ] 创建 issue 时显示 issue 模板
- [ ] Projects 看板可访问
- [ ] CONTRIBUTING.md 在 README 中链接
---
## 🎯 如何使用系统
### 对于贡献者
1. **阅读** [CONTRIBUTING.md](../../../CONTRIBUTING.md)
2. **查看** [路线图](../../roadmap/README.zh-CN.md)了解优先级
3. **开启 issue** 或找到现有的
4. **使用模板创建 PR**
5. **处理审核反馈**
6. **庆祝** 当合并时！🎉
### 对于维护者
1. **每日：** 分类新 issue/PR（15分钟）
2. **每日：** 审查分配的 PR
3. **每周：** Sprint 计划（周一）和回顾（周五）
4. **遵循：** [PR 审核指南](PR_REVIEW_GUIDE.zh-CN.md)
5. **遵循：** [项目管理指南](PROJECT_MANAGEMENT.zh-CN.md)
### 对于悬赏猎人
1. **查看** 带有 `bounty` 标签的悬赏 issue
2. **通过评论认领** issue
3. **在截止日期前完成**
4. **提交 PR** 并填写悬赏认领部分
5. **合并后获得报酬**
---
## 🔍 测试系统
### 测试 1：创建测试 PR
```bash
# 创建测试分支
git checkout -b test/pr-system-check
# 进行小改动
echo "# Test" >> TEST.md
# 提交并推送
git add TEST.md
git commit -m "test: verify PR automation system"
git push origin test/pr-system-check
# 在 GitHub 上创建 PR
# 验证：
# - PR 模板加载
# - 应用了自动标签
# - CI 检查运行
# - 添加了大小标签
```
### 测试 2：创建测试 Issue
1. 前往 **Issues → New issue**
2. 选择 **Bug Report**
3. 填写模板
4. 提交
5. 验证：
- 模板正确渲染
- Issue 可以被标签
- Issue 出现在项目看板中
### 测试 3：测试自动标签
创建改动不同区域文件的 PR：
```bash
# 测试 1：前端变更
git checkout -b test/frontend-label
touch web/src/test.tsx
git add . && git commit -m "test: frontend labeling"
git push origin test/frontend-label
# 应该得到 "area: frontend" 标签
# 测试 2：后端变更
git checkout -b test/backend-label
touch internal/test.go
git add . && git commit -m "test: backend labeling"
git push origin test/backend-label
# 应该得到 "area: backend" 标签
```
---
## 🐛 故障排除
### 问题：标签未同步
**解决方案：**
```bash
# 首先删除所有现有标签
gh label list --json name --jq '.[].name' | xargs -I {} gh label delete "{}" --yes
# 然后从 labels.yml 手动创建或通过 action 创建
```
### 问题：GitHub Actions 未运行
**检查：**
1. 仓库设置中启用了 Actions
2. 工作流文件在 `.github/workflows/` 中
3. YAML 语法有效
4. 权限设置正确
**调试：**
```bash
# 本地验证工作流
act pull_request # 使用 'act' 工具
```
### 问题：分支保护阻止 PR
**检查：**
1. 必需的检查在工作流中定义
2. 检查名称完全匹配
3. 检查正在完成（没有卡住）
**临时修复：**
- 维护者可以在紧急情况下绕过
- 如果太严格，调整保护规则
### 问题：自动标签器不工作
**检查：**
1. `.github/labeler.yml` 存在且为有效 YAML
2. labeler.yml 中定义的标签在仓库中存在
3. 工作流有 `pull-requests: write` 权限
---
## 📊 监控和维护
### 每周回顾
每周检查这些指标：
```bash
# 使用 gh CLI
gh pr list --state all --json number,createdAt,closedAt
gh issue list --state all --json number,createdAt,closedAt
# 或使用 GitHub Insights
# Repository → Insights → Pulse, Contributors, Traffic
```
### 每月维护
- [ ] 如需要审查和更新标签
- [ ] 检查工作流中的过期依赖
- [ ] 如果流程变更更新 CONTRIBUTING.md
- [ ] 审查自动化效果
- [ ] 收集社区反馈
---
## 🎓 培训资源
### 对于新贡献者
- [首次贡献指南](https://github.com/firstcontributions/first-contributions)
- [如何写 Git Commit 信息](https://chris.beams.io/posts/git-commit/)
- [Conventional Commits](https://www.conventionalcommits.org/)
### 对于维护者
- [代码审核的艺术](https://google.github.io/eng-practices/review/)
- [GitHub 项目管理](https://docs.github.com/en/issues/planning-and-tracking-with-projects)
- [维护者社区](https://maintainers.github.com/)
---
## 🎉 一切就绪！
PR 管理系统现在已准备好：
✅ 用清晰的指南引导贡献者
✅ 自动化重复任务
✅ 保持代码质量
✅ 系统性地跟踪进度
✅ 扩展社区
**有问题？** 在维护者频道联系我们或开启讨论。
**让我们构建令人惊叹的社区！🚀**

413
scripts/pr-check.sh Executable file
View File

@@ -0,0 +1,413 @@
#!/bin/bash
# 🔍 PR Health Check Script
# Analyzes your PR and gives suggestions on how to meet the new standards
# This script only analyzes and suggests - it won't modify your code
set -e
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
NC='\033[0m' # No Color
# Counters
ISSUES_FOUND=0
WARNINGS_FOUND=0
PASSED_CHECKS=0
# Helper functions
log_section() {
echo ""
echo -e "${CYAN}═══════════════════════════════════════════${NC}"
echo -e "${CYAN} $1${NC}"
echo -e "${CYAN}═══════════════════════════════════════════${NC}"
}
log_check() {
echo -e "${BLUE}🔍 Checking: $1${NC}"
}
log_pass() {
echo -e "${GREEN}✅ PASS: $1${NC}"
((PASSED_CHECKS++))
}
log_warning() {
echo -e "${YELLOW}⚠️ WARNING: $1${NC}"
((WARNINGS_FOUND++))
}
log_error() {
echo -e "${RED}❌ ISSUE: $1${NC}"
((ISSUES_FOUND++))
}
log_suggestion() {
echo -e "${CYAN}💡 Suggestion: $1${NC}"
}
log_command() {
echo -e "${GREEN} Run: ${NC}$1"
}
# Welcome
echo ""
echo "╔═══════════════════════════════════════════╗"
echo "║ NOFX PR Health Check ║"
echo "║ Analyze your PR and get suggestions ║"
echo "╚═══════════════════════════════════════════╝"
echo ""
# Check if we're in a git repo
if ! git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
log_error "Not a git repository"
exit 1
fi
# Get current branch
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
echo -e "${BLUE}Current branch: ${GREEN}$CURRENT_BRANCH${NC}"
if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "dev" ]; then
log_error "You're on the $CURRENT_BRANCH branch. Please switch to your PR branch."
exit 1
fi
# Check if upstream exists
if ! git remote | grep -q "^upstream$"; then
log_warning "Upstream remote not found"
log_suggestion "Add upstream remote:"
log_command "git remote add upstream https://github.com/tinkle-community/nofx.git"
echo ""
fi
# ═══════════════════════════════════════════
# 1. GIT BRANCH CHECKS
# ═══════════════════════════════════════════
log_section "1. Git Branch Status"
# Check if branch is up to date with upstream
log_check "Is branch based on latest upstream/dev?"
if git remote | grep -q "^upstream$"; then
git fetch upstream -q 2>/dev/null || true
if git merge-base --is-ancestor upstream/dev HEAD 2>/dev/null; then
log_pass "Branch is up to date with upstream/dev"
else
log_error "Branch is not based on latest upstream/dev"
log_suggestion "Rebase your branch:"
log_command "git fetch upstream && git rebase upstream/dev"
echo ""
fi
else
log_warning "Cannot check - upstream remote not configured"
fi
# Check for merge conflicts
log_check "Any merge conflicts?"
if git diff --check > /dev/null 2>&1; then
log_pass "No merge conflicts detected"
else
log_error "Merge conflicts detected"
log_suggestion "Resolve conflicts and commit"
fi
# ═══════════════════════════════════════════
# 2. COMMIT MESSAGE CHECKS
# ═══════════════════════════════════════════
log_section "2. Commit Messages"
# Get commits in this branch (not in upstream/dev)
if git remote | grep -q "^upstream$"; then
COMMITS=$(git log upstream/dev..HEAD --oneline 2>/dev/null || git log --oneline -10)
else
COMMITS=$(git log --oneline -10)
fi
COMMIT_COUNT=$(echo "$COMMITS" | wc -l | tr -d ' ')
echo -e "${BLUE}Found $COMMIT_COUNT commit(s) in your branch${NC}"
echo ""
# Check each commit message
echo "$COMMITS" | while read -r line; do
COMMIT_MSG=$(echo "$line" | cut -d' ' -f2-)
# Check if follows conventional commits
if echo "$COMMIT_MSG" | grep -qE "^(feat|fix|docs|style|refactor|perf|test|chore|ci|security)(\(.+\))?: .+"; then
log_pass "\"$COMMIT_MSG\""
else
log_warning "\"$COMMIT_MSG\""
log_suggestion "Should follow format: type(scope): description"
echo " Examples:"
echo " - feat(exchange): add OKX integration"
echo " - fix(trader): resolve position bug"
echo ""
fi
done
# Suggest PR title based on commits
echo ""
log_check "Suggested PR title:"
SUGGESTED_TITLE=$(git log --pretty=%s upstream/dev..HEAD 2>/dev/null | head -1 || git log --pretty=%s -1)
echo -e "${GREEN} \"$SUGGESTED_TITLE\"${NC}"
echo ""
# ═══════════════════════════════════════════
# 3. CODE QUALITY - BACKEND (Go)
# ═══════════════════════════════════════════
if find . -name "*.go" -not -path "./vendor/*" -not -path "./.git/*" | grep -q .; then
log_section "3. Backend Code Quality (Go)"
# Check if Go is installed
if ! command -v go &> /dev/null; then
log_warning "Go not installed - skipping backend checks"
log_suggestion "Install Go: https://go.dev/doc/install"
else
# Check go fmt
log_check "Go code formatting (go fmt)"
UNFORMATTED=$(gofmt -l . 2>/dev/null | grep -v vendor || true)
if [ -z "$UNFORMATTED" ]; then
log_pass "All Go files are formatted"
else
log_error "Some files need formatting:"
echo "$UNFORMATTED" | head -5 | while read -r file; do
echo " - $file"
done
log_suggestion "Format your code:"
log_command "go fmt ./..."
echo ""
fi
# Check go vet
log_check "Go static analysis (go vet)"
if go vet ./... > /tmp/vet-output.txt 2>&1; then
log_pass "No issues found by go vet"
else
log_error "Go vet found issues:"
head -10 /tmp/vet-output.txt | sed 's/^/ /'
log_suggestion "Fix the issues above"
echo ""
fi
# Check tests exist
log_check "Do tests exist?"
TEST_FILES=$(find . -name "*_test.go" -not -path "./vendor/*" | wc -l)
if [ "$TEST_FILES" -gt 0 ]; then
log_pass "Found $TEST_FILES test file(s)"
else
log_warning "No test files found"
log_suggestion "Add tests for your changes"
echo ""
fi
# Run tests
log_check "Running Go tests..."
if go test ./... -v > /tmp/test-output.txt 2>&1; then
log_pass "All tests passed"
else
log_error "Some tests failed:"
grep -E "FAIL|ERROR" /tmp/test-output.txt | head -10 | sed 's/^/ /' || true
log_suggestion "Fix failing tests:"
log_command "go test ./... -v"
echo ""
fi
fi
fi
# ═══════════════════════════════════════════
# 4. CODE QUALITY - FRONTEND
# ═══════════════════════════════════════════
if [ -d "web" ]; then
log_section "4. Frontend Code Quality"
# Check if npm is installed
if ! command -v npm &> /dev/null; then
log_warning "npm not installed - skipping frontend checks"
log_suggestion "Install Node.js: https://nodejs.org/"
else
cd web
# Check if node_modules exists
if [ ! -d "node_modules" ]; then
log_warning "Dependencies not installed"
log_suggestion "Install dependencies:"
log_command "cd web && npm install"
cd ..
else
# Check linting
log_check "Frontend linting"
if npm run lint > /tmp/lint-output.txt 2>&1; then
log_pass "No linting issues"
else
log_error "Linting issues found:"
tail -20 /tmp/lint-output.txt | sed 's/^/ /' || true
log_suggestion "Fix linting issues:"
log_command "cd web && npm run lint -- --fix"
echo ""
fi
# Check type errors
log_check "TypeScript type checking"
if npm run type-check > /tmp/typecheck-output.txt 2>&1; then
log_pass "No type errors"
else
log_error "Type errors found:"
tail -20 /tmp/typecheck-output.txt | sed 's/^/ /' || true
log_suggestion "Fix type errors in your code"
echo ""
fi
# Check build
log_check "Frontend build"
if npm run build > /tmp/build-output.txt 2>&1; then
log_pass "Build successful"
else
log_error "Build failed:"
tail -20 /tmp/build-output.txt | sed 's/^/ /' || true
log_suggestion "Fix build errors"
echo ""
fi
fi
cd ..
fi
fi
# ═══════════════════════════════════════════
# 5. PR SIZE CHECK
# ═══════════════════════════════════════════
log_section "5. PR Size"
if git remote | grep -q "^upstream$"; then
ADDED=$(git diff --numstat upstream/dev...HEAD | awk '{sum+=$1} END {print sum+0}')
DELETED=$(git diff --numstat upstream/dev...HEAD | awk '{sum+=$2} END {print sum+0}')
TOTAL=$((ADDED + DELETED))
FILES_CHANGED=$(git diff --name-only upstream/dev...HEAD | wc -l)
echo -e "${BLUE}Lines changed: ${GREEN}+$ADDED ${RED}-$DELETED ${NC}(total: $TOTAL)"
echo -e "${BLUE}Files changed: ${GREEN}$FILES_CHANGED${NC}"
echo ""
if [ "$TOTAL" -lt 100 ]; then
log_pass "Small PR (<100 lines) - ideal for quick review"
elif [ "$TOTAL" -lt 500 ]; then
log_pass "Medium PR (100-500 lines) - reasonable size"
elif [ "$TOTAL" -lt 1000 ]; then
log_warning "Large PR (500-1000 lines) - consider splitting"
log_suggestion "Breaking into smaller PRs makes review faster"
else
log_error "Very large PR (>1000 lines) - strongly consider splitting"
log_suggestion "Split into multiple smaller PRs, each with a focused change"
echo ""
fi
fi
# ═══════════════════════════════════════════
# 6. DOCUMENTATION CHECK
# ═══════════════════════════════════════════
log_section "6. Documentation"
# Check if README or docs were updated
log_check "Documentation updates"
if git remote | grep -q "^upstream$"; then
DOC_CHANGES=$(git diff --name-only upstream/dev...HEAD | grep -E "\.(md|txt)$" || true)
if [ -n "$DOC_CHANGES" ]; then
log_pass "Documentation files updated"
echo "$DOC_CHANGES" | sed 's/^/ - /'
else
# Check if this is a feature/fix that might need docs
COMMIT_TYPES=$(git log --pretty=%s upstream/dev..HEAD | grep -oE "^(feat|fix)" || true)
if [ -n "$COMMIT_TYPES" ]; then
log_warning "No documentation updates found"
log_suggestion "Consider updating docs if your changes affect usage"
echo ""
else
log_pass "No documentation update needed"
fi
fi
fi
# ═══════════════════════════════════════════
# 7. ROADMAP ALIGNMENT
# ═══════════════════════════════════════════
log_section "7. Roadmap Alignment"
log_check "Does your PR align with the roadmap?"
echo ""
echo "Current priorities (Phase 1):"
echo " ✅ Security enhancements"
echo " ✅ AI model integrations"
echo " ✅ Exchange integrations (OKX, Bybit, Lighter, EdgeX)"
echo " ✅ UI/UX improvements"
echo " ✅ Performance optimizations"
echo " ✅ Bug fixes"
echo ""
log_suggestion "Check roadmap: https://github.com/tinkle-community/nofx/blob/dev/docs/roadmap/README.md"
echo ""
# ═══════════════════════════════════════════
# FINAL REPORT
# ═══════════════════════════════════════════
log_section "Summary Report"
echo ""
echo -e "${GREEN}✅ Passed checks: $PASSED_CHECKS${NC}"
echo -e "${YELLOW}⚠️ Warnings: $WARNINGS_FOUND${NC}"
echo -e "${RED}❌ Issues found: $ISSUES_FOUND${NC}"
echo ""
# Overall assessment
if [ "$ISSUES_FOUND" -eq 0 ] && [ "$WARNINGS_FOUND" -eq 0 ]; then
echo "╔═══════════════════════════════════════════╗"
echo "║ 🎉 Excellent! Your PR looks great! ║"
echo "║ Ready to submit or update your PR ║"
echo "╚═══════════════════════════════════════════╝"
elif [ "$ISSUES_FOUND" -eq 0 ]; then
echo "╔═══════════════════════════════════════════╗"
echo "║ 👍 Good! Minor warnings found ║"
echo "║ Consider addressing warnings ║"
echo "╚═══════════════════════════════════════════╝"
elif [ "$ISSUES_FOUND" -le 3 ]; then
echo "╔═══════════════════════════════════════════╗"
echo "║ ⚠️ Issues found - Please fix ║"
echo "║ See suggestions above ║"
echo "╚═══════════════════════════════════════════╝"
else
echo "╔═══════════════════════════════════════════╗"
echo "║ ❌ Multiple issues found ║"
echo "║ Please address issues before submitting ║"
echo "╚═══════════════════════════════════════════╝"
fi
echo ""
echo "📖 Next steps:"
echo ""
if [ "$ISSUES_FOUND" -gt 0 ] || [ "$WARNINGS_FOUND" -gt 0 ]; then
echo "1. Fix the issues and warnings listed above"
echo "2. Run this script again to verify: ./scripts/pr-check.sh"
echo "3. Commit your fixes"
echo "4. Push to your PR: git push origin $CURRENT_BRANCH"
else
echo "1. Push your changes: git push origin $CURRENT_BRANCH"
echo "2. Create or update your PR on GitHub"
echo "3. Wait for automated CI checks"
echo "4. Address reviewer feedback"
fi
echo ""
echo "📚 Resources:"
echo " - Contributing Guide: https://github.com/tinkle-community/nofx/blob/dev/CONTRIBUTING.md"
echo " - Migration Guide: https://github.com/tinkle-community/nofx/blob/dev/docs/community/MIGRATION_ANNOUNCEMENT.md"
echo ""
# Cleanup temp files
rm -f /tmp/vet-output.txt /tmp/test-output.txt /tmp/lint-output.txt /tmp/typecheck-output.txt /tmp/build-output.txt
echo "✨ Analysis complete! Good luck with your PR! 🚀"
echo ""

335
scripts/pr-fix.sh Executable file
View File

@@ -0,0 +1,335 @@
#!/bin/bash
# 🔄 PR Migration Script for Contributors
# This script helps you migrate your PR to the new format
# Run this in your local fork to update your PR automatically
set -e
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# Helper functions
log_info() {
echo -e "${BLUE}ℹ️ $1${NC}"
}
log_success() {
echo -e "${GREEN}✅ $1${NC}"
}
log_warning() {
echo -e "${YELLOW}⚠️ $1${NC}"
}
log_error() {
echo -e "${RED}❌ $1${NC}"
}
confirm() {
read -p "$(echo -e ${YELLOW}"$1 (y/N): "${NC})" -n 1 -r
echo
[[ $REPLY =~ ^[Yy]$ ]]
}
# Welcome message
echo ""
echo "╔═══════════════════════════════════════════╗"
echo "║ NOFX PR Migration Tool ║"
echo "║ Migrate your PR to the new format ║"
echo "╚═══════════════════════════════════════════╝"
echo ""
# Check if we're in a git repo
if ! git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
log_error "Not a git repository. Please run this from your NOFX fork."
exit 1
fi
# Check current branch
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
log_info "Current branch: $CURRENT_BRANCH"
if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "dev" ]; then
log_warning "You're on the $CURRENT_BRANCH branch."
log_info "This script should be run on your PR branch."
# List branches
log_info "Your branches:"
git branch
echo ""
read -p "Enter your PR branch name: " PR_BRANCH
if [ -z "$PR_BRANCH" ]; then
log_error "No branch specified. Exiting."
exit 1
fi
git checkout "$PR_BRANCH" || {
log_error "Failed to checkout branch $PR_BRANCH"
exit 1
}
CURRENT_BRANCH="$PR_BRANCH"
fi
log_success "Working on branch: $CURRENT_BRANCH"
echo ""
log_info "What this script will do:"
echo " 1. ✅ Verify you're rebased on latest upstream/dev"
echo " 2. ✅ Check and format Go code (go fmt)"
echo " 3. ✅ Run Go linting (go vet)"
echo " 4. ✅ Run Go tests"
echo " 5. ✅ Check frontend code (if modified)"
echo " 6. ✅ Give you feedback and suggestions"
echo ""
log_warning "Make sure you've already run: git fetch upstream && git rebase upstream/dev"
echo ""
if ! confirm "Continue with migration?"; then
log_info "Migration cancelled"
exit 0
fi
# Step 1: Verify upstream sync
echo ""
log_info "Step 1: Verifying upstream sync..."
# Check if upstream remote exists
if ! git remote | grep -q "^upstream$"; then
log_warning "Upstream remote not found. Adding it..."
git remote add upstream https://github.com/tinkle-community/nofx.git
git fetch upstream
log_success "Added upstream remote"
fi
# Check if we're up to date with upstream/dev
if git merge-base --is-ancestor upstream/dev HEAD; then
log_success "Your branch is up to date with upstream/dev"
else
log_warning "Your branch is not based on latest upstream/dev"
log_info "Please run first: git fetch upstream && git rebase upstream/dev"
if confirm "Try to rebase now?"; then
git fetch upstream
if git rebase upstream/dev; then
log_success "Successfully rebased on upstream/dev"
else
log_error "Rebase failed. Please resolve conflicts manually."
exit 1
fi
else
log_warning "Skipping rebase. Results may not be accurate."
fi
fi
# Step 2: Backend checks (if Go files exist)
if find . -name "*.go" -not -path "./vendor/*" | grep -q .; then
echo ""
log_info "Step 2: Running backend checks..."
# Check if Go is installed
if ! command -v go &> /dev/null; then
log_warning "Go not found. Skipping backend checks."
log_info "Install Go: https://go.dev/doc/install"
else
# Format Go code
log_info "Formatting Go code..."
if go fmt ./...; then
log_success "Go code formatted"
# Check if there are changes
if ! git diff --quiet; then
log_info "Formatting created changes. Committing..."
git add .
git commit -m "chore: format Go code with go fmt" || true
fi
else
log_warning "Go formatting had issues (non-critical)"
fi
# Run go vet
log_info "Running go vet..."
if go vet ./...; then
log_success "Go vet passed"
else
log_warning "Go vet found issues. Please review them."
if confirm "Continue anyway?"; then
log_info "Continuing..."
else
exit 1
fi
fi
# Run tests
log_info "Running Go tests..."
if go test ./...; then
log_success "All Go tests passed"
else
log_warning "Some tests failed. Please fix them before pushing."
if confirm "Continue anyway?"; then
log_info "Continuing..."
else
exit 1
fi
fi
fi
else
log_info "Step 2: No Go files found, skipping backend checks"
fi
# Step 3: Frontend checks (if web directory exists)
if [ -d "web" ]; then
echo ""
log_info "Step 3: Running frontend checks..."
# Check if npm is installed
if ! command -v npm &> /dev/null; then
log_warning "npm not found. Skipping frontend checks."
log_info "Install Node.js: https://nodejs.org/"
else
cd web
# Install dependencies if needed
if [ ! -d "node_modules" ]; then
log_info "Installing dependencies..."
npm install
fi
# Run linter
log_info "Running linter..."
if npm run lint; then
log_success "Linting passed"
else
log_warning "Linting found issues"
log_info "Attempting to auto-fix..."
npm run lint -- --fix || true
# Commit fixes if any
if ! git diff --quiet; then
git add .
git commit -m "chore: fix linting issues" || true
fi
fi
# Type check
log_info "Running type check..."
if npm run type-check; then
log_success "Type checking passed"
else
log_warning "Type checking found issues. Please fix them."
fi
# Build
log_info "Testing build..."
if npm run build; then
log_success "Build successful"
else
log_error "Build failed. Please fix build errors."
cd ..
exit 1
fi
cd ..
fi
else
log_info "Step 3: No frontend changes, skipping frontend checks"
fi
# Step 4: Check PR title format
echo ""
log_info "Step 4: Checking PR title format..."
# Get the commit messages to suggest a title
COMMITS=$(git log upstream/dev..HEAD --oneline)
COMMIT_COUNT=$(echo "$COMMITS" | wc -l | tr -d ' ')
log_info "Found $COMMIT_COUNT commit(s) in your PR"
if [ "$COMMIT_COUNT" -eq 1 ]; then
SUGGESTED_TITLE=$(git log -1 --pretty=%s)
else
SUGGESTED_TITLE=$(git log --pretty=%s upstream/dev..HEAD | head -1)
fi
log_info "Current/suggested title: $SUGGESTED_TITLE"
# Check if it follows conventional commits
if echo "$SUGGESTED_TITLE" | grep -qE "^(feat|fix|docs|style|refactor|perf|test|chore|ci|security)(\(.+\))?: .+"; then
log_success "Title follows Conventional Commits format"
else
log_warning "Title doesn't follow Conventional Commits format"
echo ""
echo "Conventional Commits format:"
echo " <type>(<scope>): <description>"
echo ""
echo "Types: feat, fix, docs, style, refactor, perf, test, chore, ci, security"
echo ""
echo "Examples:"
echo " feat(exchange): add OKX integration"
echo " fix(trader): resolve position tracking bug"
echo " docs(readme): update installation guide"
echo ""
read -p "Enter new title (or press Enter to keep current): " NEW_TITLE
if [ -n "$NEW_TITLE" ]; then
log_info "You can update the PR title on GitHub after pushing"
log_info "Suggested title: $NEW_TITLE"
fi
fi
# Step 5: Push changes
echo ""
log_info "Step 5: Ready to push changes"
# Check if there are changes to push
if git diff upstream/dev..HEAD --quiet; then
log_info "No changes to push"
else
log_info "Changes ready to push to origin/$CURRENT_BRANCH"
if confirm "Push changes now?"; then
log_info "Pushing to origin/$CURRENT_BRANCH..."
if git push -f origin "$CURRENT_BRANCH"; then
log_success "Successfully pushed changes!"
else
log_error "Failed to push. You may need to push manually:"
echo " git push -f origin $CURRENT_BRANCH"
exit 1
fi
else
log_info "Skipped push. You can push manually later:"
echo " git push -f origin $CURRENT_BRANCH"
fi
fi
# Summary
echo ""
echo "╔═══════════════════════════════════════════╗"
echo "║ ✅ Migration Complete! ║"
echo "╚═══════════════════════════════════════════╝"
echo ""
log_success "Your PR has been migrated!"
echo ""
log_info "Next steps:"
echo " 1. Check your PR on GitHub"
echo " 2. Update PR title if needed (Conventional Commits format)"
echo " 3. Wait for CI checks to run"
echo " 4. Address any reviewer feedback"
echo ""
log_info "Need help? Ask in the PR comments or Telegram!"
log_info "Telegram: https://t.me/nofx_dev_community"
echo ""
log_success "Thank you for contributing to NOFX! 🚀"
echo ""