open-source-contributions

What this skill does

# Open Source Contributions Skill

**Version**: 1.1.0 | **Last Verified**: 2025-11-06 | **Production Tested**: ✅

---

## Overview

Contributing to open source projects requires understanding etiquette, conventions, and what maintainers expect. This skill helps create professional, maintainer-friendly pull requests while avoiding common mistakes that waste time and cause rejections.

**Key Focus**: Cleaning personal development artifacts, writing proper PR descriptions, following project conventions, and communicating professionally.

---

## When to Use This Skill

Use this skill when:
- Creating pull requests for public repositories
- Contributing to community open source projects
- Submitting code to projects you don't maintain
- First-time contributor to a new project
- Want to increase PR acceptance rate
- Need guidance on PR best practices

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

---

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

### Example Good PR Description

```markdown
## What?
Add OAuth2 authentication support for Google and GitHub providers

## Why?
Users have requested social login to reduce friction during signup.
This implements Key Result 2 of Q4 OKR1.

## How?
- Implemented OAuth2 flow using passport.js
- Added provider configuration in environment variables
- Created callback routes for each provider
- Updated user model to link social accounts

## Testing
1. Set up OAuth apps in Google/GitHub developer consoles
2. Add credentials to `.env` (see `.env.example`)
3. Run `npm start`
4. Click "Login with Google" and verify flow
5. Verify user profile merges correctly

## Breaking Changes
None - this is additive functionality

## Related Issues
Closes #234
Relates to #156 (social login epic)
```

### Titles: Follow Conventional Commits

**Format**: `<type>(<scope>): <description>`

**Types:**
- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation only
- `style:` - Formatting (no code change)
- `refactor:` - Code restructuring (no behavior change)
- `perf:` - Performance improvement
- `test:` - Adding/updating tests
- `build:` - Build system changes
- `ci:` - CI configuration changes
- `chore:` - Other changes (no src/test changes)

**Examples:**
```
✅ feat(auth): add OAuth2 support for Google and GitHub
✅ fix(api): resolve memory leak in worker shutdown
✅ docs(readme): update installation instructions for v2.0
✅ refactor(utils): extract validation logic to separate module

❌ Fixed stuff
❌ Updates
❌ Working on authentication (too vague)
```

---

## Commit Message Best Practices

### Structure

See `references/commit-message-guide.md` for complete guide.

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

[optional body]

[optional footer]
```

**Subject line rules:**
- 50 characters max
- Imperative mood ("Add" not "Added")
- Capitalize first word