# open-source-contributions

> Create maintainer-friendly pull requests for open source projects with clean code submissions and professional communication. Prevents 16 common mistakes that cause PR rejection.

Use when: contributing to public repositories, submitting PRs to community projects, migrating from contributor to maintainer workflows, or troubleshooting PR rejection, working on main branch errors, failing CI checks, or personal artifacts in commits.

- Author: Rod Schneider
- Repository: rodschneider/claude-skills
- Version: 20251228152025
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/rodschneider/claude-skills
- Web: https://mule.run/skillshub/@@rodschneider/claude-skills~open-source-contributions:20251228152025

---

---
name: open-source-contributions
description: |
  Create maintainer-friendly pull requests for open source projects with clean code submissions and professional communication. Prevents 16 common mistakes that cause PR rejection.

  Use when: contributing to public repositories, submitting PRs to community projects, migrating from contributor to maintainer workflows, or troubleshooting PR rejection, working on main branch errors, failing CI checks, or personal artifacts in commits.
---

# Open Source Contributions Skill

**Version**: 1.2.0 | **Last Verified**: 2025-11-28 | **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:

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

### Step 2: Review Git Status

```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?

### Step 3: Clean Personal Artifacts

**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
```

### 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`):

```markdown
## 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:
  ```typescript
  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:
   ```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!"

---

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

```bash
# ✅ 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
## 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):
```markdown
Closes #123
Fixes #456
Resolves #789

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

### GitHub CLI Essentials

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

---

## 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**: 2025-11-28