open-source-contributions

开源贡献技能

版本：1.2.0 | 上次验证：2026-01-09 | 生产环境测试：✅

---

何时使用此技能

自动触发条件：“submit PR to”“contribute to”“pull request for”“open source contribution”

创建便于维护者处理的 PR，同时避免导致 PR 被拒绝的 16 个常见错误。

---

不要在拉取请求中包含的内容

个人开发产物（绝不要包含）

规划与笔记文档：

❌ SESSION.md              # Session tracking notes
❌ NOTES.md                # Personal development notes
❌ TODO.md                 # Personal todo lists
❌ planning/*              # Planning documents directory
❌ IMPLEMENTATION_PHASES.md # Project planning
❌ DATABASE_SCHEMA.md      # Unless adding new schema to project
❌ ARCHITECTURE.md         # Unless documenting new architecture
❌ SCRATCH.md              # Temporary notes
❌ DEBUGGING.md            # Debugging notes
❌ research-logs/*         # Research notes

截图与视觉素材：

❌ screenshots/debug-*.png     # Debugging screenshots
❌ screenshots/test-*.png      # Testing screenshots
❌ screenshot-*.png            # Ad-hoc screenshots
❌ screen-recording-*.mp4      # Screen recordings
❌ before-after-local.png      # Local comparison images

✅ screenshots/feature-demo.png   # IF demonstrating feature in PR description
✅ docs/assets/ui-example.png     # IF part of documentation update

测试文件（视情况而定）：

❌ test-manual.js          # Manual testing scripts
❌ test-debug.ts           # Debugging test files
❌ quick-test.py           # Quick validation scripts
❌ scratch-test.sh         # Temporary test scripts
❌ example-local.json      # Local test data

✅ tests/feature.test.js   # Proper test suite additions
✅ tests/fixtures/data.json # Required test fixtures
✅ __tests__/component.tsx  # Component tests

构建产物与依赖项：

❌ node_modules/           # Dependencies (in .gitignore)
❌ dist/                   # Build output (in .gitignore)
❌ build/                  # Build artifacts (in .gitignore)
❌ .cache/                 # Cache files (in .gitignore)
❌ package-lock.json       # Unless explicitly required by project
❌ yarn.lock               # Unless explicitly required by project

IDE 与操作系统文件：

❌ .vscode/                # VS Code settings
❌ .idea/                  # IntelliJ settings
❌ .DS_Store               # macOS file system
❌ Thumbs.db               # Windows thumbnails
❌ *.swp, *.swo            # Vim swap files
❌ *~                      # Editor backup files

机密与敏感数据：

❌ .env                    # Environment variables (NEVER!)
❌ .env.local              # Local environment config
❌ config/local.json       # Local configuration
❌ credentials.json        # Credentials (NEVER!)
❌ *.key, *.pem            # Private keys (NEVER!)
❌ secrets/*               # Secrets directory (NEVER!)

临时与调试文件：

❌ temp/*                  # Temporary files
❌ tmp/*                   # Temporary directory
❌ debug.log               # Debug logs
❌ *.log                   # Log files
❌ dump.sql                # Database dumps
❌ core                    # Core dumps
❌ *.prof                  # Profiling output

应该包含的内容

✅ Source code changes      # The actual feature/fix
✅ Tests for changes        # Required tests for new code
✅ Documentation updates    # README, API docs, inline comments
✅ Configuration changes    # If part of the feature
✅ Migration scripts        # If needed for the feature
✅ Package.json updates     # If adding/removing dependencies
✅ Schema changes           # If part of feature (with migrations)
✅ CI/CD updates            # If needed for new workflows

---

PR 提交前清理流程

步骤 1：运行 PR 提交前检查脚本

使用随附的 scripts/pre-pr-check.sh 扫描产物：

./scripts/pre-pr-check.sh

检查内容：

• 个人文档（SESSION.md、planning/*、NOTES.md）
• PR 描述中未引用的截图
• 临时测试文件
• 大文件（>1MB）
• 文件内容中可能存在的机密信息
• PR 大小（超过 400 行时发出警告）
• 未提交的更改

步骤 2：检查 Git 状态

git status
git diff --stat

问问自己：

• 每项文件更改对于此次功能/修复是否都有必要？
• 是否有任何无关更改？
• 是否有我在开发过程中添加、但实际不需要的文件？

步骤 3：清理个人产物

手动移除：

git rm --cached SESSION.md
git rm --cached -r planning/
git rm --cached screenshots/debug-*.png
git rm --cached test-manual.js

或者使用清理脚本：

./scripts/clean-branch.sh

步骤 4：更新 .gitignore

将个人模式添加到 .git/info/exclude（仅影响你自己的检出副本）：

# Personal development artifacts
SESSION.md
NOTES.md
TODO.md
planning/
screenshots/debug-*.png
test-manual.*
scratch.*

---

编写有效的 PR 描述

使用 What/Why/How 结构

模板（参见 references/pr-template.md）：

## What?
[Brief description of what this PR does]

## Why?
[Explain the reasoning, business value, or problem being solved]

## How?
[Describe the implementation approach and key decisions]

## Testing
[Step-by-step instructions for reviewers to test]

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] CI passing
- [ ] Breaking changes documented

## Related Issues
Closes #123
Relates to #456

提交消息格式

Conventional Commits：<type>(<scope>): <subject>

类型：feat、fix、docs、refactor、test、ci、chore

示例：feat(auth): add OAuth2 support for Google and GitHub

完整指南请参见 references/commit-message-guide.md。

---

PR 大小最佳实践

有研究依据的指南：

• 理想：50 行
• 良好：<200 行
• 最大：400 行
• 超过 400 行：缺陷检出率会显著下降

保持 PR 精简：

• 每个 PR 只包含一项更改
• 使用功能开关处理尚未完成的工作：

  if (featureFlags.newAuth) {
    // New OAuth flow (incomplete but behind flag)
  } else {
    // Existing flow
  }
  

• 按层拆分：架构 → API → 前端 → 测试

---

遵循项目规范

贡献前：

1. 阅读 CONTRIBUTING.md（检查 /、/.github/、/docs/）
2. 运行格式化工具：npm run lint、npm run format
3. 遵循现有模式（查看近期已合并的 PR）
4. 提交前进行测试：

   npm test && npm run lint && npm run build
   

---

沟通最佳实践

回复模板：

• 已实现：“好主意！已在 [commit hash] 中实现”
• 不同意：“我理解你的观点。我选择了 X，因为 Y。也欢迎其他方案。”
• 请求澄清：“你能帮我理解你所说的 Z 是什么意思吗？”
• 提醒（1-2 周后）：“礼貌提醒一下这个 PR。如需修改，我很乐意配合！”

---

令维护者头疼的常见错误（避免 16 种错误）

详细说明请参阅“关键工作流规则”部分中的规则 1–3

1. 不阅读 CONTRIBUTING.md——务必先阅读并严格遵循
2. 提交个人文件——SESSION.md、planning/*、截图、临时测试（使用 PR 前检查脚本）
3. PR 过于庞大——尽量控制在 <200 行，最多 <400 行
4. 提交前不进行测试——运行完整测试套件、手动测试并留存证据（违反规则 2）
5. 处理已分配的议题——检查分配情况，并留言认领工作
6. 大型改动前未进行讨论——编码前先创建议题或留言
7. 缺乏耐心／不回复——及时回复，1–2 周后跟进
8. 不更新文档——更新 README、API 文档和内联注释
9. 忽视代码风格——使用项目的代码检查和格式化工具
10. 忽视 CI 失败——立即修复；遇到困难时寻求帮助
11. 包含无关改动——一个 PR = 一个功能（违反规则 3）
12. 未关联议题——使用“Closes #123”或“Fixes #456”
13. 提交密钥——绝不要提交 .env，并扫描密钥
14. 未提前告知就强制推送——审查开始后应避免强制推送
15. 未在本地运行构建／测试——推送前务必运行
16. 在 main/master 上工作——务必使用功能分支（违反规则 1）

---

GitHub 专属最佳实践

关键工作流规则（绝不跳过）

规则 1：务必在功能分支上工作

# ✅ CORRECT
git checkout main
git pull upstream main
git checkout -b feature/add-oauth-support
# make changes on feature branch
git commit -m "feat(auth): add OAuth support"

分支命名：feature/name、fix/issue-123、docs/update-readme、refactor/utils、test/add-tests

---

规则 2：提交 PR 前务必彻底测试

提交前务必完成：

1. 运行完整测试套件：npm test && npm run lint && npm run build
2. 手动测试（运行应用、测试功能和边界情况）
3. 留存证据（视觉改动需提供截图／视频——添加到 PR 描述中，不要提交）
4. 检查 CI 是否会通过

测试清单模板：

## Testing Performed
### Automated Tests
- ✅ All existing tests pass
- ✅ Added 12 new tests for OAuth flow
- ✅ Coverage increased from 85% to 87%

### Manual Testing
- ✅ Tested Google/GitHub OAuth flows end-to-end
- ✅ Verified error handling
- ✅ Tested on Chrome, Firefox, Safari

---

规则 3：确保 PR 聚焦且内容连贯

一个 PR = 一个功能／修复

• 理想：<200 行
• 可接受：200–400 行
• 较大：400–800 行（需要说明理由）
• 过大：>800 行（拆分）

保持聚焦：

• 规划：这个 PR 只做哪一件事？
• 开发期间：发现无关 Bug？另建分支处理
• 提交前：运行 git diff——每项改动对这个功能来说都必不可少吗？

将大型功能拆分为多个阶段：

PR #1: Database schema and models
PR #2: API endpoints
PR #3: Frontend components
PR #4: Integration and tests

---

使用草稿 PR

创建：gh pr create --draft 标记为可审查：gh pr ready（代码完成、测试通过且 CI 通过时）

关联议题

自动关闭关键词（写在 PR 描述中）：

Closes #123
Fixes #456
Resolves #789

# Multiple: Fixes #10, closes #20, resolves #30
# Cross-repo: Fixes owner/repo#123

GitHub CLI 基本用法

gh pr create --fill                    # Auto-fill from commits
gh pr create --draft                   # Draft PR
gh pr status                           # See your PRs
gh pr checks                           # View CI status
gh pr ready                            # Mark draft as ready

---

提交前检查清单

完整版本请参阅 references/pr-checklist.md。

贡献前：

• 阅读 CONTRIBUTING.md、CODE_OF_CONDUCT.md
• 在议题下留言认领工作
• 创建功能分支（绝不要在 main 上工作）

开发：

• 规则 1：在功能分支上工作
• 规则 2：彻底测试并留存证据
• 规则 3：PR 聚焦于单一功能
• 所有测试通过：npm test && npm run lint && npm run build
• 更新文档

清理：

• 运行 ./scripts/pre-pr-check.sh
• 不包含个人文件（SESSION.md、planning/*、调试截图、临时测试）
• 不包含密钥（.env、凭据）

PR 质量：

• 聚焦于一项改动（理想情况下 <200 行，最多 <400 行）
• 标题：符合 Conventional Commits 格式
• 描述：采用“内容／原因／方式”结构
• 关联议题（Closes #123）
• 视觉改动附上截图（放在 PR 描述中）

提交后：

• 监控 CI，并立即修复失败
• 及时回复反馈

---

随附资源

查看随附的示例和脚本：

• scripts/pre-pr-check.sh - 在提交前扫描残留文件
• scripts/clean-branch.sh - 移除常见的个人文件
• references/pr-template.md - PR 描述模板
• references/pr-checklist.md - 完整清单
• references/commit-message-guide.md - 约定式提交指南
• assets/good-pr-example.md - 结构良好的 PR 示例
• assets/bad-pr-example.md - 应避免的常见错误

---

关键要点

1. 规则 1：始终使用功能分支（绝不使用 main）
2. 规则 2：提交前进行全面测试（自动化测试 + 手动测试 + 证据）
3. 规则 3：让 PR 保持聚焦（理想情况下少于 200 行，每个 PR 只做一项更改）
4. 保持 PR 整洁：移除个人文件（SESSION.md、planning/*、调试截图）
5. 阅读 CONTRIBUTING.md：务必先阅读，并严格遵循
6. 关联 Issue：使用“Closes #123”自动关闭 Issue
7. 使用 ./scripts/pre-pr-check.sh：在提交前扫描残留文件

---

生产环境测试：基于真实的开源贡献和维护者反馈

Token 效率：相比反复试错，约节省 70%

避免的错误：16 个常见错误

最后验证日期：2026-01-09