118 lines
3.9 KiB
Markdown
118 lines
3.9 KiB
Markdown
# GitHub Contribution SOP
|
||
**触发**：需要给开源项目提 PR（修 bug / 加功能 / 改文档）| **禁用**：仅读代码、不需要提交变更时
|
||
**核心原则**：一个 PR 做一件事，测试通过才推，尊重项目规范
|
||
|
||
## 前置准备（每个新项目首次执行）
|
||
1. **读项目规范**（必须，不可跳过）
|
||
```
|
||
file_read('CONTRIBUTING.md') # 贡献指南
|
||
file_read('.github/PULL_REQUEST_TEMPLATE.md') # PR 模板
|
||
file_read('.github/ISSUE_TEMPLATE/') # Issue 模板
|
||
```
|
||
没有就读 README 的 Contributing 部分。如果都没有，按本 SOP 默认流程。
|
||
|
||
2. **了解项目结构和测试方式**
|
||
```
|
||
# 找测试命令
|
||
file_read('package.json') # Node: scripts.test
|
||
file_read('Makefile') # 或 Makefile
|
||
file_read('pyproject.toml') # Python: [tool.pytest] 等
|
||
```
|
||
记下测试命令备用。跑不了测试的 PR = 未验证的 PR。
|
||
|
||
3. **Fork + Clone**
|
||
```
|
||
code_run('bash', 'gh repo fork OWNER/REPO --clone && cd REPO && git remote -v')
|
||
```
|
||
|
||
## 工作流程（每个 PR）
|
||
|
||
### Step 1: 确认目标
|
||
- 读相关 Issue（如果有）
|
||
- 一句话写清楚：改什么、为什么改
|
||
- 检查：是否有人已在做？（看 Issue assignee、近期 PR）
|
||
|
||
### Step 2: 创建分支
|
||
```
|
||
code_run('bash', 'git checkout -b fix/issue-描述 && git status')
|
||
```
|
||
分支命名：`fix/xxx`（修 bug）、`feat/xxx`（新功能）、`docs/xxx`（文档）
|
||
|
||
### Step 3: 实现变更
|
||
- **最小化改动**：只改需要改的，不顺手重构无关代码
|
||
- **遵循项目风格**：缩进、命名、注释风格跟现有代码保持一致
|
||
- **每改一个逻辑点就提交一次**：
|
||
```
|
||
code_run('bash', 'git add -A && git commit -m "fix: 简洁描述"')
|
||
```
|
||
- Commit message 格式：遵循项目规范（Conventional Commits / 项目自定义）
|
||
- 没有规范就用：`type: 简短描述`
|
||
- type: fix / feat / docs / refactor / test / chore
|
||
|
||
### Step 4: 测试（不可跳过）
|
||
```
|
||
code_run('bash', '项目测试命令') # npm test / pytest / go test ./...
|
||
```
|
||
**检查项**：
|
||
- [ ] 所有现有测试通过？
|
||
- [ ] 新功能有对应测试？（如果项目有测试习惯）
|
||
- [ ] lint/type check 通过？（如果项目有）
|
||
|
||
**⛔ 测试不过不推代码。修到过为止。**
|
||
|
||
### Step 5: 推送 + 提 PR
|
||
```
|
||
code_run('bash', 'git push origin HEAD')
|
||
```
|
||
PR 内容：
|
||
- **标题**：`type: 简洁描述` 或按项目模板
|
||
- **正文**必须包含：
|
||
- 改了什么（What）
|
||
- 为什么改（Why）— 关联 Issue 用 `Fixes #123`
|
||
- 怎么测的（Testing）
|
||
- **不要写**：过度解释、无关背景、自夸
|
||
|
||
### Step 6: CI 检查
|
||
PR 提交后等 CI：
|
||
- ✅ 全过 → 等 review
|
||
- ❌ 有失败 → 看日志，修自己的问题
|
||
- CI 失败是 upstream 问题（跟你的改动无关）→ 在 PR 里说明
|
||
```
|
||
code_run('bash', 'gh run view --log-failed')
|
||
```
|
||
|
||
### Step 7: 回应 Review
|
||
- **reviewer 说改就改**，不要争论风格偏好
|
||
- **不同意的技术决定**：礼貌说明理由，但最终尊重 maintainer
|
||
- **改完后**：追加 commit + 测试 + push，不要 force push（除非 maintainer 要求 squash）
|
||
- **reviewer 要求加测试** → 加，这不是可选项
|
||
|
||
## 常见错误（避坑）
|
||
|
||
| 错误 | 正确做法 |
|
||
|------|----------|
|
||
| 一个 PR 改多件事 | 拆成多个 PR，每个独立 |
|
||
| 提了 PR 不跟进 | 每天检查 review 状态 |
|
||
| 测试没跑就推 | Step 4 是硬门槛 |
|
||
| 改了代码风格混乱 | 跟现有代码一致 |
|
||
| commit message 写 "update" | 写具体改了什么 |
|
||
| force push 覆盖 review 历史 | 追加 commit |
|
||
| PR 描述空白 | 写 What/Why/Testing |
|
||
|
||
## 跟进状态机
|
||
|
||
```
|
||
PR 提交 → 等 CI
|
||
CI ✅ → 等 Review
|
||
Review 通过 → 等 Merge ✅
|
||
Review 要改 → 改 + 测试 → 重回等 CI
|
||
CI ❌ → 修 → 重回等 CI
|
||
```
|
||
|
||
每轮跟进用：
|
||
```
|
||
code_run('bash', 'gh pr status')
|
||
code_run('bash', 'gh pr checks PR_NUMBER')
|
||
code_run('bash', 'gh pr view PR_NUMBER --comments')
|
||
```
|