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.

What NOT to Include in Pull Requests

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

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

Pre-PR Cleanup Process

Step 1: Run Pre-PR Check Script

Use the bundled scripts/pre-pr-check.sh to scan for artifacts:

./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

Step 2: Review Git Status

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?

Step 3: Clean Personal Artifacts

Manual removal:

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:

./scripts/clean-branch.sh

Step 4: Update .gitignore

Add personal patterns to .git/info/exclude (affects only YOUR checkout):

Personal development artifacts

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

Writing Effective PR Descriptions

Use the What/Why/How Structure

Template (see 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

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.

PR Sizing Best Practices

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: if (featureFlags.newAuth) { // New OAuth flow (incomplete but behind flag) } else { // Existing flow }

• Break by layer: schema → API → frontend → tests

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: 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!"

Common Mistakes That Annoy Maintainers (16 Errors Prevented)

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)

GitHub-Specific Best Practices

Critical Workflow Rules (NEVER SKIP)

RULE 1: ALWAYS Work on a Feature Branch

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

• Running full test suite: npm test && npm run lint && npm run build

• Testing manually (run app, test feature, edge cases)

• Capturing evidence (screenshots/videos for visual changes - add to PR description, NOT commits)

• Checking CI will pass

Testing checklist template:

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

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

Using Draft PRs

Create: gh pr create --draft

Mark ready: gh pr ready (when code complete, tests passing, CI passing)

Linking Issues

Auto-closing keywords (in PR description):

Closes #123 Fixes #456 Resolves #789

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

Cross-repo: Fixes owner/repo#123

GitHub CLI Essentials

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

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

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