From b2465df4e0a2246de59a85d9ccdd921fd27ebb01 Mon Sep 17 00:00:00 2001
From: Kagura <kagura.chen28@gmail.com>
Date: Wed, 15 Apr 2026 15:06:04 +0800
Subject: [PATCH] feat: add GitHub contribution SOP

---
 memory/github_contribution_sop.md | 117 ++++++++++++++++++++++++++++++
 1 file changed, 117 insertions(+)
 create mode 100644 memory/github_contribution_sop.md

diff --git a/memory/github_contribution_sop.md b/memory/github_contribution_sop.md
new file mode 100644
index 0000000..3c5992e
--- /dev/null
+++ b/memory/github_contribution_sop.md
@@ -0,0 +1,117 @@
+# 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')
+```