open-source-contributions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Open Source Contributions Skill

开源贡献技能

Version: 1.2.0 | Last Verified: 2026-01-09 | Production Tested: ✅

When to Use This Skill

何时使用此技能

Auto-triggers: "submit PR to", "contribute to", "pull request for", "open source contribution"

Create maintainer-friendly PRs while avoiding the 16 common mistakes that cause rejection.

自动触发场景: "submit PR to", "contribute to", "pull request for", "open source contribution"

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

What NOT to Include in Pull Requests

Pull Request中不应包含的内容

Personal Development Artifacts (NEVER Include)

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

Planning & Notes Documents:

❌ 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 & Visual Assets:

❌ 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 Files (Situational):

❌ 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

Build & Dependencies:

❌ 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 & OS Files:

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

Secrets & Sensitive Data:

❌ .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!)

Temporary & Debug Files:

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

规划与笔记文档：

❌ 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

What SHOULD Be Included

应该包含的内容

✅ 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

✅ 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

Pre-PR Cleanup Process

PR提交前的清理流程

Step 1: Run Pre-PR Check Script

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

Use the bundled

scripts/pre-pr-check.sh

to scan for artifacts:

bash

./scripts/pre-pr-check.sh

What it checks:

Personal documents (SESSION.md, planning/*, NOTES.md)
Screenshots not referenced in PR description
Temporary test files
Large files (>1MB)
Potential secrets in file content
PR size (warns if >400 lines)
Uncommitted changes

使用附带的

scripts/pre-pr-check.sh

扫描产物：

bash

./scripts/pre-pr-check.sh

检查内容：

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

Step 2: Review Git Status

步骤2：查看Git状态

bash

git status
git diff --stat

Ask yourself:

Is every file change necessary for THIS feature/fix?
Are there any unrelated changes?
Are there files I added during development but don't need?

bash

git status
git diff --stat

自问：

每个文件的更改对于当前功能/修复是否必要？
是否存在无关更改？
是否有开发过程中添加但不需要的文件？

Step 3: Clean Personal Artifacts

步骤3：清理个人开发产物

Manual removal:

bash

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

Or use the clean script:

bash

./scripts/clean-branch.sh

手动移除：

bash

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

或使用清理脚本：

bash

./scripts/clean-branch.sh

Step 4: Update .gitignore

步骤4：更新.gitignore

Add personal patterns to

.git/info/exclude

(affects only YOUR checkout):

undefined

将个人模式添加到

.git/info/exclude

（仅影响你的本地检出）：

undefined

Personal development artifacts

SESSION.md NOTES.md TODO.md planning/ screenshots/debug-.png test-manual. scratch.*

---

SESSION.md NOTES.md TODO.md planning/ screenshots/debug-.png test-manual. scratch.*

---

Writing Effective PR Descriptions

撰写有效的PR描述

Use the What/Why/How Structure

使用What/Why/How结构

Template (see

references/pr-template.md

markdown

undefined

模板（参见

references/pr-template.md

）：

markdown

undefined

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

Related Issues

Closes #123 Relates to #456

undefined

Closes #123 Relates to #456

undefined

Commit Message Format

提交信息格式

Conventional Commits:

<type>(<scope>): <subject>

Types:

feat

fix

docs

refactor

test

ci

chore

Example:

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

See

references/commit-message-guide.md

for complete guide.

规范提交格式：

<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 Sizing Best Practices

PR大小最佳实践

Research-backed guidelines:

Ideal: 50 lines
Good: <200 lines
Maximum: 400 lines
Beyond 400: Defect detection drops significantly

Keep PRs small:

One change per PR

Use feature flags for incomplete work:

typescript

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

Break by layer: schema → API → frontend → tests

基于研究的指南：

理想大小：50行
良好大小：<200行
最大限制：400行
超过400行：缺陷检测率显著下降

保持PR小巧：

每个PR仅包含一项更改

对未完成的工作使用功能标志：

typescript

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

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

Following Project Conventions

遵循项目约定

Before contributing:

Read CONTRIBUTING.md (check
```
/
```
,
```
/.github/
```
,
```
/docs/
```
)
Run formatters:
```
npm run lint
```
,
```
npm run format
```
Match existing patterns (review recent merged PRs)

Test before submitting:

bash

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

贡献前：

阅读CONTRIBUTING.md（检查
```
/
```
、
```
/.github/
```
、
```
/docs/
```
目录）
运行格式化工具：
```
npm run lint
```
,
```
npm run format
```
匹配现有模式（查看最近合并的PR）

提交前测试：

bash

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

Communication Best Practices

沟通最佳实践

Response templates:

Implemented: "Good idea! Implemented in [commit hash]"
Disagreement: "I see your point. I went with X because Y. Open to alternatives."
Clarification: "Could you help me understand what you mean by Z?"
Ping (after 1-2 weeks): "Gently pinging this PR. Happy to make changes!"

回复模板：

已实现："好主意！已在[提交哈希]中实现"
不同意见："我理解你的观点。我选择X是因为Y。欢迎提出替代方案。"
澄清："你能帮我理解Z的含义吗？"
提醒（1-2周后）："温馨提醒此PR。我很乐意进行更改！"

Common Mistakes That Annoy Maintainers (16 Errors Prevented)

令维护者反感的常见错误（可预防的16种错误）

See Critical Workflow Rules section for detailed guidance on Rules 1-3

Not Reading CONTRIBUTING.md - ALWAYS read first, follow exactly
Including Personal Artifacts - SESSION.md, planning/*, screenshots, temp tests (use pre-PR check script)
Massive Pull Requests - Break into <200 lines ideal, <400 max
Not Testing Before Submitting - Run full test suite, test manually, capture evidence (violates RULE 2)
Working on Assigned Issues - Check assignments, comment to claim work
Not Discussing Large Changes First - Open issue or comment before coding
Being Impatient/Unresponsive - Be responsive, ping after 1-2 weeks
Not Updating Documentation - Update README, API docs, inline comments
Ignoring Code Style - Use project's linters/formatters
Ignoring CI Failures - Fix immediately, ask for help if stuck
Including Unrelated Changes - One PR = One Feature (violates RULE 3)
Not Linking Issues - Use "Closes #123" or "Fixes #456"
Committing Secrets - Never commit .env, scan for secrets
Force-Pushing Without Warning - Avoid after review starts
Not Running Build/Tests Locally - Always run before pushing
Working on main/master - ALWAYS use feature branches (violates RULE 1)

详细指南参见关键工作流规则部分的规则1-3

未阅读CONTRIBUTING.md - 务必先阅读，严格遵循
包含个人开发产物 - SESSION.md、planning/*、截图、临时测试文件（使用PR前检查脚本）
PR过大 - 拆分为理想<200行，最大<400行
提交前未测试 - 运行完整测试套件，手动测试，收集证据（违反规则2）
处理已分配的问题 - 检查分配情况，评论以认领工作
未先讨论重大更改 - 编码前先开issue或评论
缺乏耐心/不回复 - 及时回复，1-2周后可提醒
未更新文档 - 更新README、API文档、内联注释
忽略代码风格 - 使用项目的代码检查/格式化工具
忽略CI失败 - 立即修复，遇到困难时寻求帮助
包含无关更改 - 一个PR = 一个功能（违反规则3）
未关联Issues - 使用"Closes #123"或"Fixes #456"
提交密钥 - 绝对不要提交.env，扫描密钥
未警告就强制推送 - 评审开始后避免强制推送
未在本地运行构建/测试 - 推送前务必运行
在main/master分支上工作 - 务必使用功能分支（违反规则1）

GitHub-Specific Best Practices

GitHub特定最佳实践

Critical Workflow Rules (NEVER SKIP)

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

RULE 1: ALWAYS Work on a Feature Branch

bash

undefined

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

bash

undefined

✅ 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"


**Branch naming**: `feature/name`, `fix/issue-123`, `docs/update-readme`, `refactor/utils`, `test/add-tests`

---

**RULE 2: Test Thoroughly BEFORE Submitting PR**

Never submit without:
1. Running full test suite: `npm test && npm run lint && npm run build`
2. Testing manually (run app, test feature, edge cases)
3. Capturing evidence (screenshots/videos for visual changes - add to PR description, NOT commits)
4. Checking CI will pass

**Testing checklist template:**
```markdown

git commit -m "feat(auth): add OAuth support"


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

---

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

提交前必须完成：
1. 运行完整测试套件：`npm test && npm run lint && npm run build`
2. 手动测试（运行应用，测试功能、边缘情况）
3. 收集证据（视觉更改的截图/视频 - 添加到PR描述中，而非提交中）
4. 确认CI会通过

**测试清单模板：**
```markdown

Testing Performed

Automated Tests

✅ All existing tests pass
✅ Added 12 new tests for OAuth flow
✅ Coverage increased from 85% to 87%

✅ 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


---

**RULE 3: Keep PRs Focused and Cohesive**

**One PR = One Feature/Fix**

- Ideal: <200 lines
- Acceptable: 200-400 lines
- Large: 400-800 lines (needs justification)
- Too large: >800 lines (split it)

**Keep focused:**
- Plan: What ONE thing does this PR do?
- During dev: Unrelated bug? Separate branch
- Before commit: `git diff` - Is every change necessary for THIS feature?

**Break large features into phases:**

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

---

✅ 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

---

Using Draft PRs

使用Draft PR

Create:

gh pr create --draft

Mark ready:

gh pr ready

(when code complete, tests passing, CI passing)

创建：

gh pr create --draft

标记为就绪：

gh pr ready

（代码完成、测试通过、CI通过时）

Linking Issues

关联Issues

Auto-closing keywords (in PR description):

markdown

Closes #123
Fixes #456
Resolves #789

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

markdown

Closes #123
Fixes #456
Resolves #789

Multiple: Fixes #10, closes #20, resolves #30

Cross-repo: Fixes owner/repo#123

undefined

undefined

GitHub CLI Essentials

GitHub CLI必备命令

bash

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

bash

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

Pre-Submission Checklist

提交前清单

See

references/pr-checklist.md

for complete version.

Pre-Contribution:

Read CONTRIBUTING.md, CODE_OF_CONDUCT.md
Commented on issue to claim work
Created feature branch (NEVER work on main)

Development:

RULE 1: Working on feature branch
RULE 2: Tested thoroughly with evidence
RULE 3: PR focused on single feature

All tests pass:

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

Updated documentation

Cleanup:

Ran
```
./scripts/pre-pr-check.sh
```
No personal artifacts (SESSION.md, planning/*, debug screenshots, temp tests)
No secrets (.env, credentials)

PR Quality:

Focused on one change (<200 lines ideal, <400 max)
Title: Conventional Commits format
Description: What/Why/How structure
Links to issues (Closes #123)
Screenshots for visual changes (in PR description)

Post-Submission:

Monitor CI, fix failures immediately
Respond to feedback promptly

完整版本参见

references/pr-checklist.md

。

贡献前：

阅读CONTRIBUTING.md、CODE_OF_CONDUCT.md
在issue下评论以认领工作
创建功能分支（绝对不要在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行）
标题：符合规范提交格式
描述：使用What/Why/How结构
关联了Issues（Closes #123）
视觉更改的截图（在PR描述中）

提交后：

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

Bundled Resources

附带资源

See bundled examples and scripts:

```
scripts/pre-pr-check.sh
```
- Scan for artifacts before submission
```
scripts/clean-branch.sh
```
- Remove common personal artifacts
```
references/pr-template.md
```
- PR description template
```
references/pr-checklist.md
```
- Complete checklist
```
references/commit-message-guide.md
```
- Conventional commits guide
```
assets/good-pr-example.md
```
- Well-structured PR example
```
assets/bad-pr-example.md
```
- Common mistakes to avoid

参见附带的示例和脚本：

```
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
```
- 需避免的常见错误示例

Key Takeaways

核心要点

RULE 1: ALWAYS use feature branches (never main)
RULE 2: Test thoroughly before submitting (automated + manual + evidence)
RULE 3: Keep PRs focused (<200 lines ideal, one change per PR)
Clean PRs: Remove personal artifacts (SESSION.md, planning/*, debug screenshots)
Read CONTRIBUTING.md: Always read first, follow exactly
Link Issues: Use "Closes #123" to auto-close
Use
./scripts/pre-pr-check.sh
: Scan for artifacts before submission

Production Tested: Real-world open source contributions and maintainer feedback

Token Efficiency: ~70% savings vs trial-and-error

Errors Prevented: 16 common mistakes

Last Verified: 2026-01-09

规则1：务必使用功能分支（绝对不要在main分支上工作）
规则2：提交前务必彻底测试（自动化+手动+证据）
规则3：保持PR聚焦（理想<200行，每个PR仅一项更改）
整洁的PR：移除个人开发产物（SESSION.md、planning/*、调试截图）
阅读CONTRIBUTING.md：务必先阅读，严格遵循
关联Issues：使用"Closes #123"自动关闭
使用
./scripts/pre-pr-check.sh
：提交前扫描产物

Production Tested: Real-world open source contributions and maintainer feedback

Token Efficiency: ~70% savings vs trial-and-error

Errors Prevented: 16 common mistakes

Last Verified: 2026-01-09