open-source-contributions

# 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:**
1. Read CONTRIBUTING.md (check /, /.github/, /docs/)
2. Run formatters: npm run lint, npm run format
3. Match existing patterns (review recent merged PRs)
4. 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**

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

## 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

1. **RULE 1**: ALWAYS use feature branches (never main)
2. **RULE 2**: Test thoroughly before submitting (automated + manual + evidence)
3. **RULE 3**: Keep PRs focused (<200 lines ideal, one change per PR)
4. **Clean PRs**: Remove personal artifacts (SESSION.md, planning/*, debug screenshots)
5. **Read CONTRIBUTING.md**: Always read first, follow exactly
6. **Link Issues**: Use "Closes #123" to auto-close
7. **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