Open Source Contributions

{
  "description": "|",
  "metadata": {
    "license": "MIT"
  },
  "content": "**Version**: 1.1.0 | **Last Verified**: 2025-11-06 | **Production Tested**: ✅\r\n\r\n---\r\n\r\n\r\n### Step 1: Run Pre-PR Check Script\r\n\r\nUse the bundled `scripts/pre-pr-check.sh` to scan for artifacts:\r\n\r\n```bash\r\n./scripts/pre-pr-check.sh\r\n```\r\n\r\n**What it checks:**\r\n- Personal documents (SESSION.md, planning/*, NOTES.md)\r\n- Screenshots not referenced in PR description\r\n- Temporary test files\r\n- Large files (>1MB)\r\n- Potential secrets in file content\r\n- PR size (warns if >400 lines)\r\n- Uncommitted changes\r\n\r\n### Step 2: Review Git Status\r\n\r\n```bash\r\ngit status\r\ngit diff --stat\r\n```\r\n\r\n**Ask yourself:**\r\n- Is every file change necessary for THIS feature/fix?\r\n- Are there any unrelated changes?\r\n- Are there files I added during development but don't need?\r\n\r\n### Step 3: Clean Personal Artifacts\r\n\r\n**Manual removal:**\r\n```bash\r\ngit rm --cached SESSION.md\r\ngit rm --cached -r planning/\r\ngit rm --cached screenshots/debug-*.png\r\ngit rm --cached test-manual.js\r\n```\r\n\r\n**Or use the clean script:**\r\n```bash\r\n./scripts/clean-branch.sh\r\n```\r\n\r\n### Step 4: Update .gitignore\r\n\r\nAdd personal patterns to `.git/info/exclude` (affects only YOUR checkout):\r\n```\r\n\r\n### Step 1: Read CONTRIBUTING.md\r\n\r\n**Always read this FIRST** - it's the project's law. Common locations:\r\n- `/CONTRIBUTING.md`\r\n- `/.github/CONTRIBUTING.md`\r\n- `/docs/CONTRIBUTING.md`\r\n\r\n**Key sections to check:**\r\n- Development setup\r\n- Testing requirements\r\n- Code style guidelines\r\n- Commit message format\r\n- PR process\r\n- Review expectations\r\n\r\n**Tip**: Add `/contribute` to repository URL to find beginner-friendly issues.\r\n\r\n### Step 2: Check for Style Guides\r\n\r\n**Files to look for:**\r\n- `.eslintrc`, `.eslintrc.js` (JavaScript/TypeScript linting)\r\n- `.prettierrc` (Code formatting)\r\n- `.editorconfig` (Editor settings)\r\n- `STYLE.md` (Style guide documentation)\r\n- `rustfmt.toml` (Rust formatting)\r\n- `pyproject.toml` (Python formatting)\r\n\r\n**Run formatters before committing:**\r\n```bash\r\nnpm run lint                # Check for style issues\r\nnpm run lint:fix            # Auto-fix style issues\r\nnpm run format              # Format code (Prettier, Black, etc.)\r\n```\r\n\r\n### Step 3: Match Existing Patterns\r\n\r\n**Look at recent merged PRs:**\r\n- How are files organized?\r\n- What naming conventions are used?\r\n- How verbose are comments?\r\n- What testing patterns exist?\r\n- How are imports ordered?\r\n\r\n**The Golden Rule**: \"Do things the way the project maintainers would want it done.\"\r\n\r\n### Step 4: Test Requirements\r\n\r\n**Before submitting:**\r\n```bash\r\nnpm test                    # Node projects\r\ncargo test                  # Rust projects\r\npytest                      # Python projects\r\ngo test ./...               # Go projects\r\n\r\nnpm run test:coverage\r\n\r\nnpm run lint\r\n\r\n\r\n### Fork Workflow (Standard for Open Source)\r\n\r\n**Initial setup:**\r\n```bash\r\n\r\ngit clone https://github.com/YOUR-USERNAME/project-name.git\r\ncd project-name\r\n\r\ngit remote add upstream https://github.com/ORIGINAL-OWNER/project-name.git\r\n\r\ngit remote -v\r\n```\r\n\r\n**Creating feature branch:**\r\n```bash\r\ngit checkout -b feature/add-oauth-support\r\n\r\ngit add .\r\ngit commit -m \"feat(auth): add OAuth2 support\"\r\n\r\ngit push origin feature/add-oauth-support\r\n```\r\n\r\n**Keeping fork in sync:**\r\n```bash\r\ngit fetch upstream\r\ngit checkout main\r\ngit merge upstream/main\r\ngit push origin main\r\n```\r\n\r\n---\r\n\r\n### Critical Workflow Rules (NEVER SKIP)\r\n\r\n**RULE 1: ALWAYS Work on a Feature Branch**\r\n\r\n```bash\r\ngit checkout main\r\ngit commit -m \"add feature\"  # BAD!\r\n\r\ngit checkout main\r\ngit pull upstream main  # Sync first\r\ngit checkout -b feature/add-oauth-support  # Descriptive branch name\r\n\r\n### Automated Tests\r\n- ✅ All existing tests pass\r\n- ✅ Added 12 new tests for OAuth flow\r\n- ✅ Coverage increased from 85% to 87%\r\n\r\n### Manual Testing\r\n- ✅ Tested Google OAuth flow end-to-end\r\n- ✅ Tested GitHub OAuth flow end-to-end\r\n- ✅ Verified error handling (invalid tokens, network failures)\r\n- ✅ Confirmed user profile merging works correctly\r\n- ✅ Tested on Chrome, Firefox, Safari\r\n\r\n### Evidence\r\nSee screenshots below showing successful login flow.\r\n```\r\n\r\n**Why this matters:**\r\n- Prevents CI failures that waste maintainer time\r\n- Shows you care about code quality\r\n- Demonstrates the feature actually works\r\n- Builds trust with maintainers\r\n- Catches bugs before review\r\n\r\n**Screenshots for PR descriptions:**\r\n```\r\n✅ Include: Working feature demonstration\r\n✅ Include: Before/after comparisons for changes\r\n✅ Include: Error state handling\r\n\r\n❌ Don't include: Debug screenshots in code commits\r\n❌ Don't include: Personal testing screenshots in repo\r\n❌ Don't include: Unrelated screenshots\r\n\r\nLocation: Add to PR description on GitHub, NOT as files in commits\r\n```\r\n\r\n---\r\n\r\n**RULE 3: Keep PRs Focused and Cohesive**\r\n\r\n**One PR = One Feature/Fix**\r\n\r\n```\r\n✅ GOOD: Single PR adding OAuth support\r\n  - OAuth provider configuration\r\n  - Login/callback routes\r\n  - User model updates\r\n  - Tests for OAuth flow\r\n  - Documentation for setup\r\n\r\n❌ BAD: PR with multiple unrelated changes\r\n  - OAuth support\r\n  - + Unrelated bug fix in validation\r\n  - + Random formatting changes\r\n  - + Update to README for different feature\r\n```\r\n\r\n**Why cohesive PRs matter:**\r\n- Easier to review and understand\r\n- Can be merged/rejected independently\r\n- Simpler to revert if issues found\r\n- Faster review cycles\r\n- Clear git history\r\n\r\n**How to keep PRs focused:**\r\n\r\n1. **Plan before coding:**\r\n   - What is the ONE thing this PR does?\r\n   - What files MUST be changed for this feature?\r\n   - What's the minimal set of changes needed?\r\n\r\n2. **During development:**\r\n   - If you notice an unrelated bug, create a separate branch\r\n   - If you're tempted to fix formatting, do it in a separate PR\r\n   - Stay focused on the single goal\r\n\r\n3. **Before committing:**\r\n   - Review your changes: `git diff`\r\n   - Ask: \"Is this file change necessary for THIS feature?\"\r\n   - Move unrelated changes to stash: `git stash`\r\n\r\n4. **Size guidelines:**\r\n   - Ideal: <200 lines changed\r\n   - Acceptable: 200-400 lines\r\n   - Large: 400-800 lines (needs justification)\r\n   - Too large: >800 lines (should be split)\r\n\r\n**Breaking up large features:**\r\n\r\nIf a feature is naturally large, break it into phases:\r\n\r\n```\r\nPR #1: Database schema and models\r\nPR #2: API endpoints\r\nPR #3: Frontend components\r\nPR #4: Integration and tests\r\n```\r\n\r\nEach PR:\r\n- Builds on the previous\r\n- Is independently reviewable\r\n- Adds working functionality (or is clearly marked as WIP/foundational)\r\n\r\n**Handling accidental scope creep:**\r\n\r\n```bash\r\n\r\ngit checkout main\r\ngit checkout -b fix/validation-bug\r\n\r\ngit cherry-pick <commit-hash-of-bug-fix>\r\n\r\ngit push origin fix/validation-bug\r\n\r\ngit checkout feature/add-oauth-support\r\ngit rebase -i main\r\n```\r\n\r\n---\r\n\r\n### Using Draft PRs\r\n\r\n**When to use:**\r\n- Code is work-in-progress, not ready for review\r\n- You want early feedback on approach\r\n- Starting conversation about implementation\r\n- Sharing incomplete code for collaboration\r\n\r\n**Benefits:**\r\n- Prevents accidental merging\r\n- Suppresses reviewer notifications\r\n- Clearly signals \"not ready yet\"\r\n\r\n**Create draft PR:**\r\n```bash\r\ngh pr create --draft --title \"WIP: Add OAuth support\"\r\n```\r\n\r\n**Mark ready when:**\r\n- Code is complete and tested\r\n- CI is passing\r\n- Documentation is updated\r\n- Ready for formal review\r\n\r\n```bash\r\ngh pr ready\r\n```\r\n\r\n### Linking Issues Properly\r\n\r\n**Automatic closing keywords** (in PR description or commits):\r\n```markdown\r\nCloses #123\r\nFixes #456\r\nResolves #789\r\n\r\nClose #123\r\nFix #123\r\nResolve #123\r\n\r\nCLOSES #123\r\nfixes #123\r\n\r\nFixes #10, closes #20, resolves #30\r\n\r\nFixes owner/repo#123\r\n```\r\n\r\n**Important**: Only works when merging to DEFAULT branch (usually main).\r\n\r\n### Using GitHub CLI\r\n\r\n**Creating PRs efficiently:**\r\n```bash\r\ngh pr create\r\n\r\ngh pr create --fill\r\n\r\n1. Set up OAuth apps\r\n2. Run npm start\r\n3. Test login flow\r\nEOF\r\n)\"\r\n\r\ngh pr create --reviewer username1,username2\r\n\r\n\r\n### Git Workflow\r\n\r\n```bash\r\ngit clone https://github.com/YOUR-USERNAME/project.git\r\ngit remote add upstream https://github.com/ORIGINAL/project.git\r\n\r\ngit checkout -b feature/my-feature\r\n\r\ngit add .\r\ngit commit -m \"feat: add new feature\"\r\n\r\ngit push origin feature/my-feature\r\n\r\ngit fetch upstream\r\ngit checkout main\r\ngit merge upstream/main\r\ngit push origin main\r\n\r\ngit checkout feature/my-feature\r\ngit rebase main\r\ngit push origin feature/my-feature --force-with-lease\r\n```\r\n\r\n### GitHub CLI\r\n\r\n```bash\r\ngh pr create --title \"feat: ...\" --body \"...\"\r\n\r\ngh pr status\r\ngh pr checks\r\n\r\ngh pr view\r\ngh pr diff\r\n\r\ngh pr ready              # Mark draft as ready\r\ngh pr review --approve   # Approve (if reviewer)\r\ngh pr merge             # Merge (when approved)\r\n```\r\n\r\n### Pre-PR Validation\r\n\r\n```bash\r\nnpm run lint\r\nnpm test\r\nnpm run build\r\n\r\n./scripts/pre-pr-check.sh\r\n\r\ngit status\r\ngit diff --stat",
  "name": "open-source-contributions",
  "id": "open-source-contributions",
  "sections": {
    "Resources": "**Bundled Resources:**\r\n- `scripts/pre-pr-check.sh` - Scan for artifacts before submission\r\n- `scripts/clean-branch.sh` - Remove common personal artifacts\r\n- `references/pr-template.md` - PR description template\r\n- `references/pr-checklist.md` - Complete pre-submission checklist\r\n- `references/commit-message-guide.md` - Conventional commits guide\r\n- `references/files-to-exclude.md` - Comprehensive exclusion list\r\n- `assets/good-pr-example.md` - Example of well-structured PR\r\n- `assets/bad-pr-example.md` - Common mistakes to avoid\r\n\r\n**External Resources:**\r\n- GitHub Open Source Guides: https://opensource.guide/\r\n- How to Contribute: https://opensource.guide/how-to-contribute/\r\n- Conventional Commits: https://www.conventionalcommits.org/\r\n- GitHub CLI: https://cli.github.com/manual/\r\n\r\n---\r\n\r\n**Production Tested**: ✅ Based on real-world open source contributions and maintainer feedback\r\n\r\n**Token Efficiency**: ~70% savings vs learning through trial-and-error\r\n\r\n**Errors Prevented**: 15 common mistakes documented with solutions\r\n\r\n**Last Verified**: 2025-11-05",
    "Pre-Submission Checklist": "Use this checklist before submitting ANY pull request (see `references/pr-checklist.md`).\r\n\r\n### Pre-Contribution\r\n\r\n- [ ] Read CONTRIBUTING.md thoroughly\r\n- [ ] Read CODE_OF_CONDUCT.md if present\r\n- [ ] Checked if issue should be created first\r\n- [ ] Commented on issue to claim work\r\n- [ ] Maintainer acknowledged work (for significant changes)\r\n- [ ] Forked repository (if no write access)\r\n- [ ] Set up upstream remote\r\n- [ ] Created feature branch (NEVER work on main)\r\n\r\n### Development\r\n\r\n**Critical Workflow Rules** (see detailed section above):\r\n- [ ] **RULE 1**: Working on feature branch (NOT main/master)\r\n- [ ] **RULE 2**: Tested thoroughly with evidence ready\r\n- [ ] **RULE 3**: PR is focused on single feature/fix\r\n\r\n**Code Quality:**\r\n- [ ] Code follows project style guidelines\r\n- [ ] Ran linters and formatters\r\n- [ ] All tests pass locally (`npm test`, `cargo test`, etc.)\r\n- [ ] Added tests for new functionality\r\n- [ ] Manual testing performed (run app, test feature)\r\n- [ ] Evidence captured (screenshots/videos for visual changes)\r\n- [ ] Updated relevant documentation\r\n- [ ] Commit messages follow conventions\r\n- [ ] No merge conflicts with base branch\r\n- [ ] Built project successfully (`npm run build`, etc.)\r\n\r\n### Cleanup\r\n\r\n- [ ] Ran pre-PR check script (`./scripts/pre-pr-check.sh`)\r\n- [ ] Removed personal artifacts:\r\n  - [ ] No SESSION.md or notes files\r\n  - [ ] No planning/* documents\r\n  - [ ] No debug screenshots\r\n  - [ ] No temporary test files\r\n  - [ ] No personal workflow files\r\n- [ ] Reviewed git status for unwanted files\r\n- [ ] No secrets or sensitive data\r\n- [ ] No IDE/OS-specific files\r\n- [ ] No build artifacts or dependencies\r\n\r\n### PR Quality\r\n\r\n- [ ] PR is focused on one change/issue\r\n- [ ] PR is reasonably sized (<200 lines ideal, <400 max)\r\n- [ ] No unrelated changes included\r\n- [ ] Reviewed own diff for accidental changes\r\n- [ ] Title follows conventions (Conventional Commits)\r\n- [ ] Description uses What/Why/How structure\r\n- [ ] Testing instructions included\r\n- [ ] Links to related issues (Closes #123)\r\n- [ ] Screenshots for visual changes (if demonstrating feature)\r\n- [ ] Breaking changes noted\r\n- [ ] Reviewers can understand without asking questions\r\n\r\n### Submission\r\n\r\n- [ ] CI/checks passing\r\n- [ ] Pushed to feature branch on fork\r\n- [ ] Created PR with proper description\r\n- [ ] Assigned labels (if permitted)\r\n- [ ] Requested reviewers (if known)\r\n- [ ] Linked to project/milestone (if applicable)\r\n\r\n### Post-Submission\r\n\r\n- [ ] Monitoring CI for failures\r\n- [ ] Responsive to feedback\r\n- [ ] Addressing review comments promptly\r\n- [ ] Marking conversations as resolved\r\n- [ ] Requesting re-review after changes\r\n- [ ] Thanking reviewers\r\n- [ ] Being patient while waiting\r\n\r\n---",
    "Communication Best Practices": "### Before Starting Work\r\n\r\n**Comment on the issue:**\r\n```\r\nHi! I'd like to work on this issue. My approach would be to:\r\n1. [Brief outline of approach]\r\n2. [Key implementation detail]\r\n\r\nDoes this sound good? Any guidance before I start?\r\n```\r\n\r\n**Why this matters:**\r\n- Prevents duplicate work\r\n- Gets early feedback on approach\r\n- Shows respect for maintainers' time\r\n- Establishes communication\r\n\r\n**Wait for acknowledgment** on significant changes before investing time.\r\n\r\n### Writing PR Comments\r\n\r\n**When submitting:**\r\n```\r\n@maintainer I've implemented the feature as discussed in #123.\r\nI went with approach A instead of B because [reason].\r\n\r\nReady for review when you have time. Happy to make changes!\r\n```\r\n\r\n**When responding to feedback:**\r\n```\r\nGood catch! I've updated this in commit abc1234.\r\n```\r\n\r\n```\r\nI considered that approach, but went with X because Y.\r\nHappy to discuss alternatives if you prefer a different direction.\r\n```\r\n\r\n```\r\nCould you elaborate on what you mean by Z?\r\nI want to make sure I understand correctly.\r\n```\r\n\r\n### Responding to Review Comments\r\n\r\n**Key principles:**\r\n1. **Address every comment** - Even if just \"Done\" or \"Acknowledged\"\r\n2. **Never respond in anger** - Walk away if needed, respond when calm\r\n3. **Use GitHub's review tools**:\r\n   - Mark conversations as resolved when addressed\r\n   - Request re-review after changes\r\n   - Use \"suggestion\" feature for quick fixes\r\n4. **Keep discussion on-topic** - Take tangents elsewhere\r\n5. **Be thankful** - Reviews are valuable, time-consuming work\r\n\r\n**Response templates:**\r\n- Implemented: \"Good idea! Implemented in [commit hash]\"\r\n- Question: \"Thanks for asking - I did X because Y. Thoughts?\"\r\n- Disagreement: \"I see your point. I went with X because Y. Open to alternatives if you feel strongly.\"\r\n- Clarification needed: \"Could you help me understand what you mean by Z?\"\r\n\r\n### Handling PR Rejections\r\n\r\n**Mental framework:**\r\n- It's a learning experience, not a personal failure\r\n- Rejection is normal and happens to everyone\r\n- The project's vision might differ from your approach\r\n\r\n**Steps to take:**\r\n1. **Seek clarification** - Ask why the PR was rejected politely\r\n2. **Review feedback carefully** - Identify specific concerns\r\n3. **Learn from it** - What would you do differently next time?\r\n4. **Options**:\r\n   - Rework based on feedback\r\n   - Fork and maintain your changes\r\n   - Move on to other contributions\r\n\r\n**What NOT to do:**\r\n- Don't keep commenting on declined PRs\r\n- Don't take it personally\r\n- Don't argue aggressively\r\n- Don't abandon the project entirely (unless it's truly not a fit)\r\n\r\n### Be Patient (But Know When to Ping)\r\n\r\n**Maintainers are often volunteers:**\r\n- They have day jobs, families, lives\r\n- They may be reviewing dozens of PRs\r\n- They may be dealing with complex project issues\r\n\r\n**Timeline expectations:**\r\n- Small PRs: 1-7 days\r\n- Large PRs: 1-2 weeks\r\n- Complex/controversial: Weeks to months\r\n\r\n**When to ping:**\r\n- After 1 week for small PRs\r\n- After 2 weeks for larger PRs\r\n- When CI is failing due to external changes (rebase needed)\r\n\r\n**How to ping:**\r\n```\r\nHi! Just wanted to gently ping this PR.\r\nNo rush at all, just making sure it's on your radar.\r\nHappy to answer any questions or make changes!\r\n```\r\n\r\n---",
    "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.\r\n\r\n**Key Focus**: Cleaning personal development artifacts, writing proper PR descriptions, following project conventions, and communicating professionally.\r\n\r\n---",
    "Related Issues": "Closes #234\r\nRelates to #156 (social login epic)\r\n```\r\n\r\n### Titles: Follow Conventional Commits\r\n\r\n**Format**: `<type>(<scope>): <description>`\r\n\r\n**Types:**\r\n- `feat:` - New feature\r\n- `fix:` - Bug fix\r\n- `docs:` - Documentation only\r\n- `style:` - Formatting (no code change)\r\n- `refactor:` - Code restructuring (no behavior change)\r\n- `perf:` - Performance improvement\r\n- `test:` - Adding/updating tests\r\n- `build:` - Build system changes\r\n- `ci:` - CI configuration changes\r\n- `chore:` - Other changes (no src/test changes)\r\n\r\n**Examples:**\r\n```\r\n✅ feat(auth): add OAuth2 support for Google and GitHub\r\n✅ fix(api): resolve memory leak in worker shutdown\r\n✅ docs(readme): update installation instructions for v2.0\r\n✅ refactor(utils): extract validation logic to separate module\r\n\r\n❌ Fixed stuff\r\n❌ Updates\r\n❌ Working on authentication (too vague)\r\n```\r\n\r\n---",
    "Breaking Changes": "None - this is additive functionality",
    "Why?": "User request for social login",
    "How?": "- Implemented OAuth2 flow using passport.js\r\n- Added provider configuration in environment variables\r\n- Created callback routes for each provider\r\n- Updated user model to link social accounts",
    "Testing": "gh pr create --draft\r\n```\r\n\r\n**Other useful commands:**\r\n```bash\r\ngh pr status              # See your PRs\r\ngh pr checks              # View CI status\r\ngh pr view                # View current PR\r\ngh pr diff                # See PR diff\r\ngh pr ready               # Mark draft as ready\r\ngh pr merge               # Merge PR (when approved)\r\n```\r\n\r\n---",
    "When to Use This Skill": "Use this skill when:\r\n- Creating pull requests for public repositories\r\n- Contributing to community open source projects\r\n- Submitting code to projects you don't maintain\r\n- First-time contributor to a new project\r\n- Want to increase PR acceptance rate\r\n- Need guidance on PR best practices\r\n\r\n**Auto-triggers on phrases**: \"submit PR to\", \"contribute to\", \"pull request for\", \"open source contribution\"\r\n\r\n---",
    "Examples": "See bundled examples for complete before/after comparisons:\r\n- `assets/good-pr-example.md` - Well-structured PR\r\n- `assets/bad-pr-example.md` - Common mistakes to avoid\r\n\r\n---",
    "What?": "Add OAuth2 authentication",
    "Checklist": "- [ ] Tests added/updated\r\n- [ ] Documentation updated\r\n- [ ] CI passing\r\n- [ ] Breaking changes documented",
    "Common Mistakes That Annoy Maintainers": "### The Top 16 Mistakes\r\n\r\n**See Critical Workflow Rules section for detailed guidance on Rules 1-3**\r\n\r\n**1. Not Reading CONTRIBUTING.md**\r\n- Impact: Wasted effort, rejected PRs, frustrated maintainers\r\n- Fix: ALWAYS read this file first, follow instructions exactly\r\n\r\n**2. Including Personal Development Artifacts**\r\n- Impact: Messy PRs, reveals internal workflow, unprofessional\r\n- Fix: Use pre-PR check script, clean artifacts before submission\r\n- Examples: SESSION.md, planning/*, screenshots, temp test files\r\n\r\n**3. Submitting Massive Pull Requests**\r\n- Impact: Overwhelming to review, harder to find bugs, delays merge\r\n- Fix: Break into smaller PRs (<200 lines ideal)\r\n\r\n**4. Not Testing Code Before Submitting (Violates RULE 2)**\r\n- Impact: CI failures, bugs in production, maintainer has to fix, loss of trust\r\n- Fix: See **RULE 2** - Run full test suite, test manually, capture evidence (screenshots/videos), verify CI will pass\r\n\r\n**5. Working on Already Assigned Issues**\r\n- Impact: Duplicate work, wasted time for both contributors\r\n- Fix: Check issue assignments, comment to claim work\r\n\r\n**6. Not Discussing Changes First (for large changes)**\r\n- Impact: Unwanted features, rejected PRs, wasted development time\r\n- Fix: Open issue or comment to discuss before coding\r\n\r\n**7. Being Impatient or Unresponsive**\r\n- Impact: PRs stall, maintainers move on, contributions abandoned\r\n- Fix: Be responsive but patient, ping respectfully after 1-2 weeks\r\n\r\n**8. Not Updating Documentation**\r\n- Impact: Users and developers confused by undocumented changes\r\n- Fix: Update README, API docs, inline comments as needed\r\n\r\n**9. Ignoring Code Style Standards**\r\n- Impact: Messy codebase, maintainer has to fix formatting\r\n- Fix: Use project's linters/formatters, match existing style\r\n\r\n**10. Ignoring CI Failures**\r\n- Impact: Can't merge, blocks progress, maintainer has to investigate\r\n- Fix: Monitor CI, fix failures immediately, ask for help if stuck\r\n\r\n**11. Including Unrelated Changes (Violates RULE 3)**\r\n- Impact: Difficult review, harder to revert, scope creep, confusing git history\r\n- Fix: See **RULE 3** - One PR = One Feature. Keep focused, split unrelated changes into separate branches/PRs\r\n\r\n**12. Not Linking Issues Properly**\r\n- Impact: Lost context, manual issue closing, harder to track\r\n- Fix: Use \"Closes #123\" or \"Fixes #456\" in PR description\r\n\r\n**13. Committing Secrets or Sensitive Data**\r\n- Impact: Security risk, requires emergency response, potential breach\r\n- Fix: Use .gitignore, scan for secrets, never commit .env files\r\n\r\n**14. Force-Pushing Without Warning**\r\n- Impact: Breaks reviewer's local copies, loses comments\r\n- Fix: Avoid force-push after review starts, warn if necessary\r\n\r\n**15. Not Running Build/Tests Locally**\r\n- Impact: CI failures for obvious issues, wastes CI resources\r\n- Fix: Always run `npm run build` and `npm test` before pushing\r\n\r\n**16. Working Directly on main/master Branch (Violates RULE 1)**\r\n- Impact: Messy git history, conflicts with upstream, can't work on multiple features, difficult to sync fork\r\n- Fix: See **RULE 1** - ALWAYS create feature branches (`git checkout -b feature/my-feature`), NEVER commit to main\r\n\r\n---",
    "Commit Message Best Practices": "### Structure\r\n\r\nSee `references/commit-message-guide.md` for complete guide.\r\n\r\n```\r\n<type>(<scope>): <subject>\r\n\r\n[optional body]\r\n\r\n[optional footer]\r\n```\r\n\r\n**Subject line rules:**\r\n- 50 characters max\r\n- Imperative mood (\"Add\" not \"Added\")\r\n- Capitalize first word\r\n- No period at end\r\n- Describe WHAT changed\r\n\r\n**Body rules (optional):**\r\n- 72 characters per line\r\n- Explain WHY (code shows WHAT)\r\n- Separate from subject with blank line\r\n\r\n**Footer (optional):**\r\n- Reference issues: `Closes #123`\r\n- Note breaking changes: `BREAKING CHANGE: ...`\r\n\r\n### Examples\r\n\r\n**Good:**\r\n```\r\nfix: prevent race condition in cache invalidation\r\n\r\nThe cache invalidation logic wasn't thread-safe, causing\r\noccasional race conditions when multiple workers tried to\r\ninvalidate the same key simultaneously.\r\n\r\nAdded mutex locks around the critical section and tests\r\nto verify thread-safety.\r\n\r\nFixes #456\r\n```\r\n\r\n**Bad:**\r\n```\r\nFixed bug                          # Too vague\r\nWIP                               # Not descriptive\r\nasdf                              # Meaningless\r\nUpdated auth.js                   # Describes file, not change\r\nFixed the issue with the thing    # No specifics\r\n```\r\n\r\n---",
    "Pre-PR Cleanup Process": "SESSION.md\r\nNOTES.md\r\nTODO.md\r\nplanning/\r\nscreenshots/debug-*.png\r\ntest-manual.*\r\nscratch.*\r\n```\r\n\r\n---",
    "PR Sizing Best Practices": "### Ideal Sizes\r\n\r\n**Research-backed guidelines:**\r\n- **Ideal**: 50 lines of code\r\n- **Good**: Under 200 lines\r\n- **Maximum**: 400 lines\r\n- **Beyond 400**: Defect detection drops significantly\r\n\r\n**Why small PRs matter:**\r\n- Faster reviews (maintainers can review in one sitting)\r\n- Easier to find bugs\r\n- Simpler to revert if needed\r\n- Reduced merge conflicts\r\n- More focused discussions\r\n\r\n### How to Keep PRs Small\r\n\r\n**1. One Change = One PR**\r\n```\r\n❌ BAD: Refactor auth module + add OAuth + fix bug + update docs (800 lines)\r\n\r\n✅ GOOD:\r\n  PR #1: Refactor auth module (150 lines)\r\n  PR #2: Add OAuth support (200 lines)\r\n  PR #3: Fix authentication bug (50 lines)\r\n  PR #4: Update authentication docs (80 lines)\r\n```\r\n\r\n**2. Separate Refactoring from Features**\r\n```\r\n❌ BAD: Add feature X + refactor related code (500 lines)\r\n\r\n✅ GOOD:\r\n  PR #1: Refactor to prepare for feature X (200 lines)\r\n  PR #2: Add feature X (150 lines)\r\n```\r\n\r\n**3. Use Feature Flags**\r\nShip incomplete features behind flags, merge early and often:\r\n```typescript\r\nif (featureFlags.newAuth) {\r\n  // New OAuth flow (incomplete but behind flag)\r\n} else {\r\n  // Existing flow\r\n}\r\n```\r\n\r\n**4. Break Down by Layer**\r\n```\r\nFor \"User Authentication\" feature:\r\n  PR #1: Database schema + migrations (100 lines)\r\n  PR #2: API endpoints (150 lines)\r\n  PR #3: Frontend components (200 lines)\r\n  PR #4: Tests + documentation (150 lines)\r\n```\r\n\r\n### When Large PRs Are Acceptable\r\n\r\n- Initial project scaffolding\r\n- Generated code (clearly marked as such)\r\n- Large refactors that can't be split (explain why in description)\r\n- Documentation rewrites\r\n- Dependency updates (automated)\r\n\r\n**If unavoidable**: Add clear section headers in PR description to guide review.\r\n\r\n---",
    "Key Takeaways": "1. **Clean Your PRs** - Remove all personal development artifacts before submission\r\n2. **Read CONTRIBUTING.md** - Always read this first, follow instructions exactly\r\n3. **Keep PRs Small** - <200 lines ideal, one change per PR\r\n4. **Test Everything** - Locally before submitting, fix CI failures immediately\r\n5. **Follow Conventions** - Style, commits, testing, documentation\r\n6. **Communicate Well** - Be respectful, responsive, patient, and professional\r\n7. **Link Issues** - Use \"Closes #123\" to auto-close related issues\r\n8. **Be Patient** - Maintainers are often volunteers with limited time\r\n9. **Learn from Feedback** - Every review is a learning opportunity\r\n10. **Use Automation** - Scripts, templates, and checklists prevent mistakes\r\n\r\n---",
    "GitHub-Specific Best Practices": "git commit -m \"feat(auth): add OAuth support\"\r\n```\r\n\r\n**Why this matters:**\r\n- Keeps main clean and in sync with upstream\r\n- Allows working on multiple features simultaneously\r\n- Makes it easy to abandon or restart work\r\n- Required by most open source projects\r\n- Prevents conflicts and messy git history\r\n\r\n**Branch naming conventions:**\r\n```\r\nfeature/descriptive-name    # New features\r\nfix/issue-123               # Bug fixes\r\ndocs/update-readme          # Documentation\r\nrefactor/extract-utils      # Refactoring\r\ntest/add-unit-tests         # Test additions\r\n```\r\n\r\n---\r\n\r\n**RULE 2: Test Thoroughly BEFORE Submitting PR**\r\n\r\nNever submit a PR without:\r\n\r\n1. **Running the full test suite locally:**\r\n   ```bash\r\n   npm test              # Node.js\r\n   cargo test            # Rust\r\n   pytest                # Python\r\n   go test ./...         # Go\r\n   ```\r\n\r\n2. **Testing manually** (hands-on verification):\r\n   - Run the application\r\n   - Test the specific feature you added\r\n   - Test edge cases and error conditions\r\n   - Verify it works as intended\r\n\r\n3. **Capturing evidence** (for visual/UI changes):\r\n   - Take screenshots showing the feature working\r\n   - Record a short demo video if complex\r\n   - Include in PR description to demonstrate functionality\r\n\r\n4. **Checking CI will pass:**\r\n   ```bash\r\n   npm run lint          # Linting\r\n   npm run build         # Build succeeds\r\n   npm run type-check    # TypeScript checks\r\n   ```\r\n\r\n**Example testing checklist for a new OAuth feature:**\r\n```markdown",
    "Writing Effective PR Descriptions": "### Use the What/Why/How Structure\r\n\r\n**Template** (see `references/pr-template.md`):\r\n\r\n```markdown",
    "Following Project Conventions": "npm run build\r\n```\r\n\r\n**Never submit a PR with:**\r\n- Failing tests\r\n- Failing lints\r\n- Build errors\r\n- Untested new code (if tests are required)\r\n\r\n---",
    "Quick Command Reference": "git diff\r\ngit log --oneline -5\r\n```\r\n\r\n---",
    "Testing Performed": "gh pr create \\\r\n  --title \"feat(auth): add OAuth support\" \\\r\n  --body \"$(cat <<'EOF'",
    "What NOT to Include in Pull Requests": "### Personal Development Artifacts (NEVER Include)\r\n\r\n**Planning & Notes Documents:**\r\n```\r\n❌ SESSION.md              # Session tracking notes\r\n❌ NOTES.md                # Personal development notes\r\n❌ TODO.md                 # Personal todo lists\r\n❌ planning/*              # Planning documents directory\r\n❌ IMPLEMENTATION_PHASES.md # Project planning\r\n❌ DATABASE_SCHEMA.md      # Unless adding new schema to project\r\n❌ ARCHITECTURE.md         # Unless documenting new architecture\r\n❌ SCRATCH.md              # Temporary notes\r\n❌ DEBUGGING.md            # Debugging notes\r\n❌ research-logs/*         # Research notes\r\n```\r\n\r\n**Screenshots & Visual Assets:**\r\n```\r\n❌ screenshots/debug-*.png     # Debugging screenshots\r\n❌ screenshots/test-*.png      # Testing screenshots\r\n❌ screenshot-*.png            # Ad-hoc screenshots\r\n❌ screen-recording-*.mp4      # Screen recordings\r\n❌ before-after-local.png      # Local comparison images\r\n\r\n✅ screenshots/feature-demo.png   # IF demonstrating feature in PR description\r\n✅ docs/assets/ui-example.png     # IF part of documentation update\r\n```\r\n\r\n**Test Files (Situational):**\r\n```\r\n❌ test-manual.js          # Manual testing scripts\r\n❌ test-debug.ts           # Debugging test files\r\n❌ quick-test.py           # Quick validation scripts\r\n❌ scratch-test.sh         # Temporary test scripts\r\n❌ example-local.json      # Local test data\r\n\r\n✅ tests/feature.test.js   # Proper test suite additions\r\n✅ tests/fixtures/data.json # Required test fixtures\r\n✅ __tests__/component.tsx  # Component tests\r\n```\r\n\r\n**Build & Dependencies:**\r\n```\r\n❌ node_modules/           # Dependencies (in .gitignore)\r\n❌ dist/                   # Build output (in .gitignore)\r\n❌ build/                  # Build artifacts (in .gitignore)\r\n❌ .cache/                 # Cache files (in .gitignore)\r\n❌ package-lock.json       # Unless explicitly required by project\r\n❌ yarn.lock               # Unless explicitly required by project\r\n```\r\n\r\n**IDE & OS Files:**\r\n```\r\n❌ .vscode/                # VS Code settings\r\n❌ .idea/                  # IntelliJ settings\r\n❌ .DS_Store               # macOS file system\r\n❌ Thumbs.db               # Windows thumbnails\r\n❌ *.swp, *.swo            # Vim swap files\r\n❌ *~                      # Editor backup files\r\n```\r\n\r\n**Secrets & Sensitive Data:**\r\n```\r\n❌ .env                    # Environment variables (NEVER!)\r\n❌ .env.local              # Local environment config\r\n❌ config/local.json       # Local configuration\r\n❌ credentials.json        # Credentials (NEVER!)\r\n❌ *.key, *.pem            # Private keys (NEVER!)\r\n❌ secrets/*               # Secrets directory (NEVER!)\r\n```\r\n\r\n**Temporary & Debug Files:**\r\n```\r\n❌ temp/*                  # Temporary files\r\n❌ tmp/*                   # Temporary directory\r\n❌ debug.log               # Debug logs\r\n❌ *.log                   # Log files\r\n❌ dump.sql                # Database dumps\r\n❌ core                    # Core dumps\r\n❌ *.prof                  # Profiling output\r\n```\r\n\r\n### What SHOULD Be Included\r\n\r\n```\r\n✅ Source code changes      # The actual feature/fix\r\n✅ Tests for changes        # Required tests for new code\r\n✅ Documentation updates    # README, API docs, inline comments\r\n✅ Configuration changes    # If part of the feature\r\n✅ Migration scripts        # If needed for the feature\r\n✅ Package.json updates     # If adding/removing dependencies\r\n✅ Schema changes           # If part of feature (with migrations)\r\n✅ CI/CD updates            # If needed for new workflows\r\n```\r\n\r\n---"
  }
}

---
name: open-source-contributions
description: |
  Use this skill when contributing code to open source projects. The skill covers proper pull request creation, avoiding common mistakes that annoy maintainers, cleaning up personal development artifacts before submission, writing effective PR descriptions, following project conventions, and communicating professionally with maintainers. It prevents 16 common contribution mistakes including working on main branch, not testing before PR submission, including unrelated changes, submitting planning documents, session notes, temporary test files, screenshots, and other personal artifacts. Includes 3 Critical Workflow Rules that must NEVER be skipped: (1) Always work on feature branches, (2) Test thoroughly with evidence before PR, (3) Keep PRs focused on single feature. The skill includes automation scripts to validate PRs before submission, templates for PR descriptions and commit messages, and comprehensive checklists. This skill should be used whenever creating pull requests for public repositories, contributing to community projects, or submitting code to projects you don't own.

  Keywords: open source contributions, github pull request, PR best practices, contribution guidelines, feature branch workflow, PR description, commit messages, open source etiquette, maintainer-friendly PR, PR checklist, clean PR, avoid personal artifacts, session notes cleanup, planning docs cleanup, test before PR, unrelated changes, working on main branch, focused PR, single feature PR, professional communication, community contributions, public repository contributions, fork workflow, upstream sync
license: MIT
metadata:
  version: "1.1.0"
  author: "Jeremy Dawes - Jezweb"
  repository: "https://github.com/jezweb/claude-skills"
  last_verified: "2025-11-06"
  production_tested: true
  token_savings: "~70%"
  errors_prevented: 16
---

# 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
- No period at end
- Describe WHAT changed

**Body rules (optional):**
- 72 characters per line
- Explain WHY (code shows WHAT)
- Separate from subject with blank line

**Footer (optional):**
- Reference issues: `Closes #123`
- Note breaking changes: `BREAKING CHANGE: ...`

### Examples

**Good:**
```
fix: prevent race condition in cache invalidation

The cache invalidation logic wasn't thread-safe, causing
occasional race conditions when multiple workers tried to
invalidate the same key simultaneously.

Added mutex locks around the critical section and tests
to verify thread-safety.

Fixes #456
```

**Bad:**
```
Fixed bug                          # Too vague
WIP                               # Not descriptive
asdf                              # Meaningless
Updated auth.js                   # Describes file, not change
Fixed the issue with the thing    # No specifics
```

---

## PR Sizing Best Practices

### Ideal Sizes

**Research-backed guidelines:**
- **Ideal**: 50 lines of code
- **Good**: Under 200 lines
- **Maximum**: 400 lines
- **Beyond 400**: Defect detection drops significantly

**Why small PRs matter:**
- Faster reviews (maintainers can review in one sitting)
- Easier to find bugs
- Simpler to revert if needed
- Reduced merge conflicts
- More focused discussions

### How to Keep PRs Small

**1. One Change = One PR**
```
❌ BAD: Refactor auth module + add OAuth + fix bug + update docs (800 lines)

✅ GOOD:
  PR #1: Refactor auth module (150 lines)
  PR #2: Add OAuth support (200 lines)
  PR #3: Fix authentication bug (50 lines)
  PR #4: Update authentication docs (80 lines)
```

**2. Separate Refactoring from Features**
```
❌ BAD: Add feature X + refactor related code (500 lines)

✅ GOOD:
  PR #1: Refactor to prepare for feature X (200 lines)
  PR #2: Add feature X (150 lines)
```

**3. Use Feature Flags**
Ship incomplete features behind flags, merge early and often:
```typescript
if (featureFlags.newAuth) {
  // New OAuth flow (incomplete but behind flag)
} else {
  // Existing flow
}
```

**4. Break Down by Layer**
```
For "User Authentication" feature:
  PR #1: Database schema + migrations (100 lines)
  PR #2: API endpoints (150 lines)
  PR #3: Frontend components (200 lines)
  PR #4: Tests + documentation (150 lines)
```

### When Large PRs Are Acceptable

- Initial project scaffolding
- Generated code (clearly marked as such)
- Large refactors that can't be split (explain why in description)
- Documentation rewrites
- Dependency updates (automated)

**If unavoidable**: Add clear section headers in PR description to guide review.

---

## Following Project Conventions

### Step 1: Read CONTRIBUTING.md

**Always read this FIRST** - it's the project's law. Common locations:
- `/CONTRIBUTING.md`
- `/.github/CONTRIBUTING.md`
- `/docs/CONTRIBUTING.md`

**Key sections to check:**
- Development setup
- Testing requirements
- Code style guidelines
- Commit message format
- PR process
- Review expectations

**Tip**: Add `/contribute` to repository URL to find beginner-friendly issues.

### Step 2: Check for Style Guides

**Files to look for:**
- `.eslintrc`, `.eslintrc.js` (JavaScript/TypeScript linting)
- `.prettierrc` (Code formatting)
- `.editorconfig` (Editor settings)
- `STYLE.md` (Style guide documentation)
- `rustfmt.toml` (Rust formatting)
- `pyproject.toml` (Python formatting)

**Run formatters before committing:**
```bash
npm run lint                # Check for style issues
npm run lint:fix            # Auto-fix style issues
npm run format              # Format code (Prettier, Black, etc.)
```

### Step 3: Match Existing Patterns

**Look at recent merged PRs:**
- How are files organized?
- What naming conventions are used?
- How verbose are comments?
- What testing patterns exist?
- How are imports ordered?

**The Golden Rule**: "Do things the way the project maintainers would want it done."

### Step 4: Test Requirements

**Before submitting:**
```bash
# Run full test suite
npm test                    # Node projects
cargo test                  # Rust projects
pytest                      # Python projects
go test ./...               # Go projects

# Check coverage (if required)
npm run test:coverage

# Run linters
npm run lint

# Build the project
npm run build
```

**Never submit a PR with:**
- Failing tests
- Failing lints
- Build errors
- Untested new code (if tests are required)

---

## Communication Best Practices

### Before Starting Work

**Comment on the issue:**
```
Hi! I'd like to work on this issue. My approach would be to:
1. [Brief outline of approach]
2. [Key implementation detail]

Does this sound good? Any guidance before I start?
```

**Why this matters:**
- Prevents duplicate work
- Gets early feedback on approach
- Shows respect for maintainers' time
- Establishes communication

**Wait for acknowledgment** on significant changes before investing time.

### Writing PR Comments

**When submitting:**
```
@maintainer I've implemented the feature as discussed in #123.
I went with approach A instead of B because [reason].

Ready for review when you have time. Happy to make changes!
```

**When responding to feedback:**
```
Good catch! I've updated this in commit abc1234.
```

```
I considered that approach, but went with X because Y.
Happy to discuss alternatives if you prefer a different direction.
```

```
Could you elaborate on what you mean by Z?
I want to make sure I understand correctly.
```

### Responding to Review Comments

**Key principles:**
1. **Address every comment** - Even if just "Done" or "Acknowledged"
2. **Never respond in anger** - Walk away if needed, respond when calm
3. **Use GitHub's review tools**:
   - Mark conversations as resolved when addressed
   - Request re-review after changes
   - Use "suggestion" feature for quick fixes
4. **Keep discussion on-topic** - Take tangents elsewhere
5. **Be thankful** - Reviews are valuable, time-consuming work

**Response templates:**
- Implemented: "Good idea! Implemented in [commit hash]"
- Question: "Thanks for asking - I did X because Y. Thoughts?"
- Disagreement: "I see your point. I went with X because Y. Open to alternatives if you feel strongly."
- Clarification needed: "Could you help me understand what you mean by Z?"

### Handling PR Rejections

**Mental framework:**
- It's a learning experience, not a personal failure
- Rejection is normal and happens to everyone
- The project's vision might differ from your approach

**Steps to take:**
1. **Seek clarification** - Ask why the PR was rejected politely
2. **Review feedback carefully** - Identify specific concerns
3. **Learn from it** - What would you do differently next time?
4. **Options**:
   - Rework based on feedback
   - Fork and maintain your changes
   - Move on to other contributions

**What NOT to do:**
- Don't keep commenting on declined PRs
- Don't take it personally
- Don't argue aggressively
- Don't abandon the project entirely (unless it's truly not a fit)

### Be Patient (But Know When to Ping)

**Maintainers are often volunteers:**
- They have day jobs, families, lives
- They may be reviewing dozens of PRs
- They may be dealing with complex project issues

**Timeline expectations:**
- Small PRs: 1-7 days
- Large PRs: 1-2 weeks
- Complex/controversial: Weeks to months

**When to ping:**
- After 1 week for small PRs
- After 2 weeks for larger PRs
- When CI is failing due to external changes (rebase needed)

**How to ping:**
```
Hi! Just wanted to gently ping this PR.
No rush at all, just making sure it's on your radar.
Happy to answer any questions or make changes!
```

---

## Common Mistakes That Annoy Maintainers

### The Top 16 Mistakes

**See Critical Workflow Rules section for detailed guidance on Rules 1-3**

**1. Not Reading CONTRIBUTING.md**
- Impact: Wasted effort, rejected PRs, frustrated maintainers
- Fix: ALWAYS read this file first, follow instructions exactly

**2. Including Personal Development Artifacts**
- Impact: Messy PRs, reveals internal workflow, unprofessional
- Fix: Use pre-PR check script, clean artifacts before submission
- Examples: SESSION.md, planning/*, screenshots, temp test files

**3. Submitting Massive Pull Requests**
- Impact: Overwhelming to review, harder to find bugs, delays merge
- Fix: Break into smaller PRs (<200 lines ideal)

**4. Not Testing Code Before Submitting (Violates RULE 2)**
- Impact: CI failures, bugs in production, maintainer has to fix, loss of trust
- Fix: See **RULE 2** - Run full test suite, test manually, capture evidence (screenshots/videos), verify CI will pass

**5. Working on Already Assigned Issues**
- Impact: Duplicate work, wasted time for both contributors
- Fix: Check issue assignments, comment to claim work

**6. Not Discussing Changes First (for large changes)**
- Impact: Unwanted features, rejected PRs, wasted development time
- Fix: Open issue or comment to discuss before coding

**7. Being Impatient or Unresponsive**
- Impact: PRs stall, maintainers move on, contributions abandoned
- Fix: Be responsive but patient, ping respectfully after 1-2 weeks

**8. Not Updating Documentation**
- Impact: Users and developers confused by undocumented changes
- Fix: Update README, API docs, inline comments as needed

**9. Ignoring Code Style Standards**
- Impact: Messy codebase, maintainer has to fix formatting
- Fix: Use project's linters/formatters, match existing style

**10. Ignoring CI Failures**
- Impact: Can't merge, blocks progress, maintainer has to investigate
- Fix: Monitor CI, fix failures immediately, ask for help if stuck

**11. Including Unrelated Changes (Violates RULE 3)**
- Impact: Difficult review, harder to revert, scope creep, confusing git history
- Fix: See **RULE 3** - One PR = One Feature. Keep focused, split unrelated changes into separate branches/PRs

**12. Not Linking Issues Properly**
- Impact: Lost context, manual issue closing, harder to track
- Fix: Use "Closes #123" or "Fixes #456" in PR description

**13. Committing Secrets or Sensitive Data**
- Impact: Security risk, requires emergency response, potential breach
- Fix: Use .gitignore, scan for secrets, never commit .env files

**14. Force-Pushing Without Warning**
- Impact: Breaks reviewer's local copies, loses comments
- Fix: Avoid force-push after review starts, warn if necessary

**15. Not Running Build/Tests Locally**
- Impact: CI failures for obvious issues, wastes CI resources
- Fix: Always run `npm run build` and `npm test` before pushing

**16. Working Directly on main/master Branch (Violates RULE 1)**
- Impact: Messy git history, conflicts with upstream, can't work on multiple features, difficult to sync fork
- Fix: See **RULE 1** - ALWAYS create feature branches (`git checkout -b feature/my-feature`), NEVER commit to main

---

## GitHub-Specific Best Practices

### Fork Workflow (Standard for Open Source)

**Initial setup:**
```bash
# 1. Fork repository on GitHub (click Fork button)

# 2. Clone YOUR fork
git clone https://github.com/YOUR-USERNAME/project-name.git
cd project-name

# 3. Add upstream remote
git remote add upstream https://github.com/ORIGINAL-OWNER/project-name.git

# 4. Verify remotes
git remote -v
# origin    https://github.com/YOUR-USERNAME/project-name.git (fetch)
# origin    https://github.com/YOUR-USERNAME/project-name.git (push)
# upstream  https://github.com/ORIGINAL-OWNER/project-name.git (fetch)
# upstream  https://github.com/ORIGINAL-OWNER/project-name.git (push)
```

**Creating feature branch:**
```bash
# NEVER work on main/master directly!
git checkout -b feature/add-oauth-support

# Make changes...
git add .
git commit -m "feat(auth): add OAuth2 support"

# Push to YOUR fork
git push origin feature/add-oauth-support
```

**Keeping fork in sync:**
```bash
git fetch upstream
git checkout main
git merge upstream/main
git push origin main
```

---

### Critical Workflow Rules (NEVER SKIP)

**RULE 1: ALWAYS Work on a Feature Branch**

```bash
# ❌ NEVER DO THIS
git checkout main
# make changes directly on main
git commit -m "add feature"  # BAD!

# ✅ ALWAYS DO THIS
git checkout main
git pull upstream main  # Sync first
git checkout -b feature/add-oauth-support  # Descriptive branch name
# make changes on feature branch
git commit -m "feat(auth): add OAuth support"
```

**Why this matters:**
- Keeps main clean and in sync with upstream
- Allows working on multiple features simultaneously
- Makes it easy to abandon or restart work
- Required by most open source projects
- Prevents conflicts and messy git history

**Branch naming conventions:**
```
feature/descriptive-name    # New features
fix/issue-123               # Bug fixes
docs/update-readme          # Documentation
refactor/extract-utils      # Refactoring
test/add-unit-tests         # Test additions
```

---

**RULE 2: Test Thoroughly BEFORE Submitting PR**

Never submit a PR without:

1. **Running the full test suite locally:**
   ```bash
   npm test              # Node.js
   cargo test            # Rust
   pytest                # Python
   go test ./...         # Go
   ```

2. **Testing manually** (hands-on verification):
   - Run the application
   - Test the specific feature you added
   - Test edge cases and error conditions
   - Verify it works as intended

3. **Capturing evidence** (for visual/UI changes):
   - Take screenshots showing the feature working
   - Record a short demo video if complex
   - Include in PR description to demonstrate functionality

4. **Checking CI will pass:**
   ```bash
   npm run lint          # Linting
   npm run build         # Build succeeds
   npm run type-check    # TypeScript checks
   ```

**Example testing checklist for a new OAuth feature:**
```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 OAuth flow end-to-end
- ✅ Tested GitHub OAuth flow end-to-end
- ✅ Verified error handling (invalid tokens, network failures)
- ✅ Confirmed user profile merging works correctly
- ✅ Tested on Chrome, Firefox, Safari

### Evidence
See screenshots below showing successful login flow.
```

**Why this matters:**
- Prevents CI failures that waste maintainer time
- Shows you care about code quality
- Demonstrates the feature actually works
- Builds trust with maintainers
- Catches bugs before review

**Screenshots for PR descriptions:**
```
✅ Include: Working feature demonstration
✅ Include: Before/after comparisons for changes
✅ Include: Error state handling

❌ Don't include: Debug screenshots in code commits
❌ Don't include: Personal testing screenshots in repo
❌ Don't include: Unrelated screenshots

Location: Add to PR description on GitHub, NOT as files in commits
```

---

**RULE 3: Keep PRs Focused and Cohesive**

**One PR = One Feature/Fix**

```
✅ GOOD: Single PR adding OAuth support
  - OAuth provider configuration
  - Login/callback routes
  - User model updates
  - Tests for OAuth flow
  - Documentation for setup

❌ BAD: PR with multiple unrelated changes
  - OAuth support
  - + Unrelated bug fix in validation
  - + Random formatting changes
  - + Update to README for different feature
```

**Why cohesive PRs matter:**
- Easier to review and understand
- Can be merged/rejected independently
- Simpler to revert if issues found
- Faster review cycles
- Clear git history

**How to keep PRs focused:**

1. **Plan before coding:**
   - What is the ONE thing this PR does?
   - What files MUST be changed for this feature?
   - What's the minimal set of changes needed?

2. **During development:**
   - If you notice an unrelated bug, create a separate branch
   - If you're tempted to fix formatting, do it in a separate PR
   - Stay focused on the single goal

3. **Before committing:**
   - Review your changes: `git diff`
   - Ask: "Is this file change necessary for THIS feature?"
   - Move unrelated changes to stash: `git stash`

4. **Size guidelines:**
   - Ideal: <200 lines changed
   - Acceptable: 200-400 lines
   - Large: 400-800 lines (needs justification)
   - Too large: >800 lines (should be split)

**Breaking up large features:**

If a feature is naturally large, break it into phases:

```
PR #1: Database schema and models
PR #2: API endpoints
PR #3: Frontend components
PR #4: Integration and tests
```

Each PR:
- Builds on the previous
- Is independently reviewable
- Adds working functionality (or is clearly marked as WIP/foundational)

**Handling accidental scope creep:**

```bash
# You added OAuth + accidentally fixed a bug
# Split them into separate commits and PRs:

# 1. Create bug fix branch from main
git checkout main
git checkout -b fix/validation-bug

# 2. Cherry-pick just the bug fix commits
git cherry-pick <commit-hash-of-bug-fix>

# 3. Submit bug fix PR separately
git push origin fix/validation-bug

# 4. Continue with OAuth PR
git checkout feature/add-oauth-support
# Remove bug fix commits if needed
git rebase -i main
```

---

### Using Draft PRs

**When to use:**
- Code is work-in-progress, not ready for review
- You want early feedback on approach
- Starting conversation about implementation
- Sharing incomplete code for collaboration

**Benefits:**
- Prevents accidental merging
- Suppresses reviewer notifications
- Clearly signals "not ready yet"

**Create draft PR:**
```bash
gh pr create --draft --title "WIP: Add OAuth support"
```

**Mark ready when:**
- Code is complete and tested
- CI is passing
- Documentation is updated
- Ready for formal review

```bash
gh pr ready
```

### Linking Issues Properly

**Automatic closing keywords** (in PR description or commits):
```markdown
Closes #123
Fixes #456
Resolves #789

# Also works:
Close #123
Fix #123
Resolve #123

# Case insensitive:
CLOSES #123
fixes #123

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

# Cross-repo:
Fixes owner/repo#123
```

**Important**: Only works when merging to DEFAULT branch (usually main).

### Using GitHub CLI

**Creating PRs efficiently:**
```bash
# Interactive (prompts for title/body)
gh pr create

# Auto-fill from commits
gh pr create --fill

# Complete non-interactive
gh pr create \
  --title "feat(auth): add OAuth support" \
  --body "$(cat <<'EOF'
## What?
Add OAuth2 authentication

## Why?
User request for social login

## Testing
1. Set up OAuth apps
2. Run npm start
3. Test login flow
EOF
)"

# With reviewers
gh pr create --reviewer username1,username2

# Draft PR
gh pr create --draft
```

**Other useful commands:**
```bash
gh pr status              # See your PRs
gh pr checks              # View CI status
gh pr view                # View current PR
gh pr diff                # See PR diff
gh pr ready               # Mark draft as ready
gh pr merge               # Merge PR (when approved)
```

---

## Pre-Submission Checklist

Use this checklist before submitting ANY pull request (see `references/pr-checklist.md`).

### Pre-Contribution

- [ ] Read CONTRIBUTING.md thoroughly
- [ ] Read CODE_OF_CONDUCT.md if present
- [ ] Checked if issue should be created first
- [ ] Commented on issue to claim work
- [ ] Maintainer acknowledged work (for significant changes)
- [ ] Forked repository (if no write access)
- [ ] Set up upstream remote
- [ ] Created feature branch (NEVER work on main)

### Development

**Critical Workflow Rules** (see detailed section above):
- [ ] **RULE 1**: Working on feature branch (NOT main/master)
- [ ] **RULE 2**: Tested thoroughly with evidence ready
- [ ] **RULE 3**: PR is focused on single feature/fix

**Code Quality:**
- [ ] Code follows project style guidelines
- [ ] Ran linters and formatters
- [ ] All tests pass locally (`npm test`, `cargo test`, etc.)
- [ ] Added tests for new functionality
- [ ] Manual testing performed (run app, test feature)
- [ ] Evidence captured (screenshots/videos for visual changes)
- [ ] Updated relevant documentation
- [ ] Commit messages follow conventions
- [ ] No merge conflicts with base branch
- [ ] Built project successfully (`npm run build`, etc.)

### Cleanup

- [ ] Ran pre-PR check script (`./scripts/pre-pr-check.sh`)
- [ ] Removed personal artifacts:
  - [ ] No SESSION.md or notes files
  - [ ] No planning/* documents
  - [ ] No debug screenshots
  - [ ] No temporary test files
  - [ ] No personal workflow files
- [ ] Reviewed git status for unwanted files
- [ ] No secrets or sensitive data
- [ ] No IDE/OS-specific files
- [ ] No build artifacts or dependencies

### PR Quality

- [ ] PR is focused on one change/issue
- [ ] PR is reasonably sized (<200 lines ideal, <400 max)
- [ ] No unrelated changes included
- [ ] Reviewed own diff for accidental changes
- [ ] Title follows conventions (Conventional Commits)
- [ ] Description uses What/Why/How structure
- [ ] Testing instructions included
- [ ] Links to related issues (Closes #123)
- [ ] Screenshots for visual changes (if demonstrating feature)
- [ ] Breaking changes noted
- [ ] Reviewers can understand without asking questions

### Submission

- [ ] CI/checks passing
- [ ] Pushed to feature branch on fork
- [ ] Created PR with proper description
- [ ] Assigned labels (if permitted)
- [ ] Requested reviewers (if known)
- [ ] Linked to project/milestone (if applicable)

### Post-Submission

- [ ] Monitoring CI for failures
- [ ] Responsive to feedback
- [ ] Addressing review comments promptly
- [ ] Marking conversations as resolved
- [ ] Requesting re-review after changes
- [ ] Thanking reviewers
- [ ] Being patient while waiting

---

## Quick Command Reference

### Git Workflow

```bash
# Setup
git clone https://github.com/YOUR-USERNAME/project.git
git remote add upstream https://github.com/ORIGINAL/project.git

# Create feature branch
git checkout -b feature/my-feature

# Make changes and commit
git add .
git commit -m "feat: add new feature"

# Push to your fork
git push origin feature/my-feature

# Keep fork synced
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

# Rebase feature branch if needed
git checkout feature/my-feature
git rebase main
git push origin feature/my-feature --force-with-lease
```

### GitHub CLI

```bash
# Create PR
gh pr create --title "feat: ..." --body "..."

# Check status
gh pr status
gh pr checks

# View PR
gh pr view
gh pr diff

# Manage PR
gh pr ready              # Mark draft as ready
gh pr review --approve   # Approve (if reviewer)
gh pr merge             # Merge (when approved)
```

### Pre-PR Validation

```bash
# Run checks
npm run lint
npm test
npm run build

# Use skill script
./scripts/pre-pr-check.sh

# Check git status
git status
git diff --stat

# Review changes
git diff
git log --oneline -5
```

---

## Examples

See bundled examples for complete before/after comparisons:
- `assets/good-pr-example.md` - Well-structured PR
- `assets/bad-pr-example.md` - Common mistakes to avoid

---

## Key Takeaways

1. **Clean Your PRs** - Remove all personal development artifacts before submission
2. **Read CONTRIBUTING.md** - Always read this first, follow instructions exactly
3. **Keep PRs Small** - <200 lines ideal, one change per PR
4. **Test Everything** - Locally before submitting, fix CI failures immediately
5. **Follow Conventions** - Style, commits, testing, documentation
6. **Communicate Well** - Be respectful, responsive, patient, and professional
7. **Link Issues** - Use "Closes #123" to auto-close related issues
8. **Be Patient** - Maintainers are often volunteers with limited time
9. **Learn from Feedback** - Every review is a learning opportunity
10. **Use Automation** - Scripts, templates, and checklists prevent mistakes

---

## Resources

**Bundled Resources:**
- `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 pre-submission checklist
- `references/commit-message-guide.md` - Conventional commits guide
- `references/files-to-exclude.md` - Comprehensive exclusion list
- `assets/good-pr-example.md` - Example of well-structured PR
- `assets/bad-pr-example.md` - Common mistakes to avoid

**External Resources:**
- GitHub Open Source Guides: https://opensource.guide/
- How to Contribute: https://opensource.guide/how-to-contribute/
- Conventional Commits: https://www.conventionalcommits.org/
- GitHub CLI: https://cli.github.com/manual/

---

**Production Tested**: ✅ Based on real-world open source contributions and maintainer feedback

**Token Efficiency**: ~70% savings vs learning through trial-and-error

**Errors Prevented**: 15 common mistakes documented with solutions

**Last Verified**: 2025-11-05