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:

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

Example Good PR Description

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