---

name: open-source-contributions description: Open source contribution best practices with PR validation scripts. Use for pull requests, community contributions, or encountering personal artifacts in PRs, working on main branch, untested submissions, unrelated changes, unfocused PRs.

Keywords: open source contributions, github pull request, PR best practices, contribution guidelines, feature branch workflow, PR description, commit messages, open source etiquette, maintainer-friendly PR, PR checklist, clean PR, avoid personal artifacts, session notes cleanup, planning docs cleanup, test before PR, unrelated changes, working on main branch, focused PR, single feature PR, professional communication, community contributions, public repository contributions, fork workflow, upstream sync license: MIT metadata: version: "2.0.0" last_verified: "2025-11-18" production_tested: true token_savings: "~70%" errors_prevented: 16 templates_included: 4 references_included: 3

Open Source Contributions Skill

Version: 2.0.0 | Last Verified: 2025-11-18 | Production Tested: ✅

---

Quick Start (5 Minutes)

1. Read Contribution Guidelines

cat CONTRIBUTING.md       # ALWAYS read first
cat CODE_OF_CONDUCT.md

2. Fork and Clone

# Fork on GitHub, then:
git clone https://github.com/YOUR-USERNAME/project.git
cd project
git remote add upstream https://github.com/ORIGINAL-OWNER/project.git

3. Create Feature Branch

# NEVER work on main!
git checkout -b feature/add-oauth-support

4. Make Changes, Test, Commit

# Make changes
npm test
npm run build
npm run lint

# Commit
git commit -m "feat(auth): add OAuth2 support"

5. Validate Before PR

# Run validation script
bash scripts/validate-pr.sh  # Load from templates/validate-pr.sh

# Push
git push origin feature/add-oauth-support

6. Create PR on GitHub

Use template from templates/pr-description.md - include What/Why/How/Testing/Evidence

Load references/workflow-guide.md for complete step-by-step workflow.

---

The 3 Critical Rules (NEVER SKIP)

RULE 1: Always Work on Feature Branches

NEVER commit directly to main/master branch

# ❌ WRONG: Working on main
git checkout main
git commit -m "add feature"  # DON'T DO THIS

# ✅ CORRECT: Create feature branch
git checkout -b feature/my-feature
git commit -m "add feature"  # This is correct

Why?

• Keeps main clean for syncing with upstream
• Allows working on multiple features simultaneously
• Makes it easy to discard or restart feature work
• Prevents messy git history

Recovery if you committed to main:

# Move commits to feature branch
git branch feature/my-feature    # Create branch with commits
git reset --hard upstream/main   # Reset main to upstream
git checkout feature/my-feature  # Switch to feature branch

---

RULE 2: Test Thoroughly with Evidence Before PR

NEVER submit untested code

Required testing:

1. All existing tests pass locally
2. New tests added for new functionality
3. Manual testing with screenshots/videos
4. Build succeeds
5. Linting passes

Required evidence in PR description:

## Testing

### Automated Tests
- [x] All existing tests pass (450/450)
- [x] Added 15 new tests for feature
- [x] Coverage: 92%

### Manual Testing
- [x] Tested on Chrome, Firefox, Safari
- [x] Tested edge cases and error states
- [x] Performance testing (handles 1000+ items)

### Evidence
- Screenshot: [feature working](link)
- Video: [full walkthrough](link)

Why?

• Maintainers can't merge untested code
• CI failures waste everyone's time
• Bugs in production damage project reputation
• Shows professionalism and respect

---

RULE 3: Keep PRs Focused on Single Feature

One PR = One Feature

# ❌ WRONG: Multiple unrelated changes
git checkout -b feature/oauth-and-bugfixes
# Adding OAuth + fixing 5 unrelated bugs

# ✅ CORRECT: Separate branches for separate concerns
git checkout -b feature/add-oauth        # Just OAuth
git checkout -b fix/pagination-bug       # Just pagination fix
git checkout -b fix/login-redirect       # Just login fix

Good PRs:

• Fix one bug
• Add one feature
• Refactor one module
• Update one set of related docs

Bad PRs:

• Fix bug + add feature
• Multiple unrelated features
• Refactor + new functionality

Why?

• Easier to review (reviewers can focus)
• Easier to revert if issues found
• Clearer git history
• Faster merge (less discussion needed)

Load references/error-catalog.md for all 16 mistakes and detailed fixes.

---

Top 5 Mistakes

For complete catalog: Load references/error-catalog.md when making any contribution to see all 16 mistakes, detailed fixes, and prevention strategies.

Quick list (most common):

1. Including personal artifacts - SESSION.md, planning/*, debug screenshots, temp test files
2. Not testing before PR - Submitting untested code causing CI failures (Violates RULE 2)
3. Working on main branch - Committing directly to main instead of feature branch (Violates RULE 1)
4. Including unrelated changes - Mixing multiple features/fixes in one PR (Violates RULE 3)
5. Submitting massive PRs - PRs >500 lines are hard to review (split into <200 line chunks)

Prevention: Run templates/validate-pr.sh before every PR to catch these automatically.

For detailed fixes and code examples: Load references/error-catalog.md

---

Common Use Cases

For complete workflows: Load references/workflow-guide.md when implementing any contribution pattern.

Quick trigger guide:

1. Fix existing bug → Sync main, create fix/ branch, test, commit with "Fixes #123"
2. Add new feature → Create issue first, get approval, create feature/ branch, implement incrementally
3. Update documentation → Create docs/ branch, edit, commit with "Closes #789"
4. First-time contribution → Read CONTRIBUTING.md, fork, clone, add upstream, find good first issue
5. Validate before PR → Run templates/validate-pr.sh (automated) or templates/pre-submission-checklist.md (manual)

For step-by-step commands and patterns: Load references/workflow-guide.md → specific workflow section

---

When to Load References

Load references/workflow-guide.md when:

• First-time contributor to open source
• Need complete fork-to-PR walkthrough
• Troubleshooting git issues (merge conflicts, committed to main, etc.)
• Want step-by-step guide for each contribution type
• Need command reference for common operations

Load references/error-catalog.md when:

• Making any type of contribution (prevention)
• PR was rejected/feedback received
• Want to understand all 16 common mistakes
• Need detailed fixes for specific issues
• Want prevention checklist

Load references/pr-templates.md when:

• Creating pull request description
• Need commit message format
• PR includes breaking changes
• Large PR that needs justification
• Reopening old/abandoned PR

---

What NOT to Include in PRs

Personal Development Artifacts (NEVER include):

❌ SESSION.md, NOTES.md, TODO.md          # Session notes
❌ planning/*, research-logs/*            # Planning docs
❌ screenshots/debug-*, screenshots/test-* # Debug screenshots
❌ test-manual.js, quick-test.py          # Temp test files
❌ IMPLEMENTATION_PHASES.md               # Project planning
❌ SCRATCH.md, DEBUGGING.md               # Temporary notes

Use validation script to check:

bash scripts/validate-pr.sh  # Load from templates/

Load references/error-catalog.md → Mistake #2 for complete list.

---

Using Bundled Resources

References (references/)

• workflow-guide.md - Complete fork-to-PR workflow (setup → contribution → after merge)
• error-catalog.md - All 16 common mistakes with fixes and prevention
• pr-templates.md - Templates for PR descriptions, commit messages, breaking changes

Templates (templates/)

• pr-description.md - Copy-paste PR description template
• pre-submission-checklist.md - Complete checklist before submitting
• validate-pr.sh - Automated validation script (run before every PR)

---

Pre-Submission Checklist

For complete checklist: Load templates/pre-submission-checklist.md when validating PR before submission.

Quick essentials:

• Code: Tests pass, build succeeds, linting passes
• Git: On feature branch, no personal artifacts, focused changes
• Docs: README/comments/CHANGELOG updated if needed
• PR: Clear title, detailed description with testing evidence, issues linked, <500 lines

Automated validation: Run templates/validate-pr.sh to check automatically.

---

Quick Command Reference

For complete command reference: Load references/workflow-guide.md when setting up fork, syncing with upstream, or managing contribution workflow.

Essential commands:

• Setup: git clone → git remote add upstream
• Sync: git pull upstream main → git push origin main
• Work: git checkout -b feature/name → test → commit → bash scripts/validate-pr.sh
• Submit: git push origin feature/name → create PR on GitHub
• After merge: sync main → git branch -d feature/name

Load references/workflow-guide.md → "Quick Command Reference" for detailed commands.

---

Communication Best Practices

For complete templates: Load references/pr-templates.md when writing PR descriptions or communicating with maintainers.

Key principles:

• Be patient (wait 1-2 weeks before follow-up)
• Be responsive (reply within 48 hours)
• Be professional (always courteous)
• Be appreciative (maintainers are volunteers)

Common scenarios: Claiming issues, receiving feedback, following up on PRs - all covered in references with example templates.

---

Troubleshooting

For complete solutions: Load references/workflow-guide.md → "Troubleshooting" when encountering git issues or PR problems.

Common problems:

• Committed to main by mistake
• Need to remove personal artifacts
• PR too large

All solutions with commands available in workflow-guide.md

---

Key Takeaways

The 3 Critical Rules (detailed in lines 79-185):

1. ALWAYS work on feature branches (never main)
2. ALWAYS test thoroughly before PR (with evidence)
3. ALWAYS keep PRs focused (one feature/fix per PR)

Before Every PR: Run validate-pr.sh script, remove artifacts, test thoroughly

Load references/error-catalog.md to avoid all 16 common mistakes.

---

Resources

References (references/):

• error-catalog.md - All 16 common mistakes that annoy maintainers with prevention strategies
• pr-templates.md - PR description templates and writing best practices
• workflow-guide.md - Complete contribution workflow (includes commit message best practices, PR sizing guidelines)

Templates (templates/):

• validate-pr.sh - Pre-PR validation script

---

Related Skills

• github-project-automation - GitHub workflow automation
• feature-dev - Feature development best practices
• claude-code-bash-patterns - Git command patterns

---

Questions? Issues?

1. Check references/error-catalog.md for all 16 mistakes
2. Review references/workflow-guide.md for complete workflow
3. Use references/pr-templates.md for PR descriptions
4. Run templates/validate-pr.sh before every PR