313 lines
6.7 KiB
Markdown
313 lines
6.7 KiB
Markdown
---
|
|
name: github-contributor
|
|
description: Strategic guide for becoming an effective GitHub contributor. Covers opportunity discovery, project selection, high-quality PR creation, and reputation building. Use when looking to contribute to open-source projects, building GitHub presence, or learning contribution best practices.
|
|
---
|
|
|
|
# GitHub Contributor
|
|
|
|
Strategic guide for becoming an effective GitHub contributor and building your open-source reputation.
|
|
|
|
## Prerequisites
|
|
|
|
- Install GitHub CLI and verify availability: `gh --version`
|
|
- Authenticate before running commands: `gh auth status || gh auth login`
|
|
|
|
## The Strategy
|
|
|
|
**Core insight**: Many open-source projects have room for improvement. By contributing high-quality PRs, you:
|
|
- Build contributor reputation
|
|
- Learn from top codebases
|
|
- Expand professional network
|
|
- Create public proof of skills
|
|
|
|
## Contribution Types
|
|
|
|
### 1. Documentation Improvements
|
|
|
|
**Lowest barrier, high impact.**
|
|
|
|
- Fix typos, grammar, unclear explanations
|
|
- Add missing examples
|
|
- Improve README structure
|
|
- Translate documentation
|
|
|
|
```
|
|
Opportunity signals:
|
|
- "docs", "documentation" labels
|
|
- Issues asking "how do I..."
|
|
- Outdated screenshots or examples
|
|
```
|
|
|
|
### 2. Code Quality Enhancements
|
|
|
|
**Medium effort, demonstrates technical skill.**
|
|
|
|
- Fix linter warnings
|
|
- Add type annotations
|
|
- Improve error messages
|
|
- Refactor for readability
|
|
|
|
```
|
|
Opportunity signals:
|
|
- "good first issue" label
|
|
- "tech debt" or "refactor" labels
|
|
- Code without tests
|
|
```
|
|
|
|
### 3. Bug Fixes
|
|
|
|
**High impact, builds trust.**
|
|
|
|
- Reproduce and fix reported bugs
|
|
- Add regression tests
|
|
- Document root cause
|
|
|
|
```
|
|
Opportunity signals:
|
|
- "bug" label with reproduction steps
|
|
- Issues with many thumbs up
|
|
- Stale bugs (maintainers busy)
|
|
```
|
|
|
|
### 4. Feature Additions
|
|
|
|
**Highest effort, highest visibility.**
|
|
|
|
- Implement requested features
|
|
- Add integrations
|
|
- Performance improvements
|
|
|
|
```
|
|
Opportunity signals:
|
|
- "help wanted" label
|
|
- Features with clear specs
|
|
- Issues linked to roadmap
|
|
```
|
|
|
|
## Project Selection
|
|
|
|
### Good First Projects
|
|
|
|
| Criteria | Why |
|
|
|----------|-----|
|
|
| Active maintainers | PRs get reviewed |
|
|
| Clear contribution guide | Know expectations |
|
|
| "good first issue" labels | Curated entry points |
|
|
| Recent merged PRs | Project is alive |
|
|
| Friendly community | Supportive feedback |
|
|
|
|
### Red Flags
|
|
|
|
- No activity in 6+ months
|
|
- Many open PRs without review
|
|
- Hostile issue discussions
|
|
- No contribution guidelines
|
|
|
|
### Finding Projects
|
|
|
|
```bash
|
|
# GitHub search for good first issues
|
|
gh search issues "good first issue" --language=python --sort=created --state=open
|
|
|
|
# Search by topic
|
|
gh search repos "topic:cli" --sort=stars --limit=20
|
|
|
|
# Find repos you use
|
|
# Check dependencies in your projects
|
|
```
|
|
|
|
## PR Excellence
|
|
|
|
### Before Writing Code
|
|
|
|
```
|
|
Pre-PR Checklist:
|
|
- [ ] Read CONTRIBUTING.md
|
|
- [ ] Check existing PRs for similar changes
|
|
- [ ] Comment on issue to claim it
|
|
- [ ] Understand project conventions
|
|
- [ ] Set up development environment
|
|
```
|
|
|
|
### Writing the PR
|
|
|
|
**Title**: Clear, conventional format
|
|
|
|
```
|
|
feat(config): add support for YAML config files
|
|
fix(pool): resolve race condition in connection pool
|
|
docs(readme): update installation instructions for Windows
|
|
refactor(validation): extract validation logic into separate module
|
|
```
|
|
|
|
**Evidence loop**: Prove the change with a reproducible fail -> fix -> pass loop.
|
|
|
|
- Reproduce the failure with one command.
|
|
- Apply the fix.
|
|
- Rerun the exact same command and capture the passing output.
|
|
- Compare baseline vs fixed vs reference behavior.
|
|
- Redact local paths, secrets, tokens, and internal hostnames before posting logs or screenshots.
|
|
|
|
**Description**: Structured and thorough
|
|
|
|
````markdown
|
|
## Summary
|
|
[What this PR does in 1-2 sentences]
|
|
|
|
## Motivation
|
|
[Why this change is needed]
|
|
|
|
## Changes
|
|
- [Change 1]
|
|
- [Change 2]
|
|
|
|
## Evidence Loop
|
|
Command:
|
|
```bash
|
|
# Baseline (before fix)
|
|
[command]
|
|
|
|
# Fixed (after fix, same command)
|
|
[command]
|
|
```
|
|
|
|
Raw output:
|
|
```text
|
|
[paste baseline output]
|
|
```
|
|
|
|
```text
|
|
[paste fixed output]
|
|
```
|
|
|
|
## Comparison
|
|
| Case | Command / Scenario | Result | Evidence |
|
|
|------|--------------------|--------|----------|
|
|
| Baseline | `[same command]` | Fail | [raw output block] |
|
|
| Fixed | `[same command]` | Pass | [raw output block] |
|
|
| Reference | [spec, issue, or main branch behavior] | Expected | [link or note] |
|
|
|
|
## Sources/Attribution
|
|
- [Issue, docs, or code references]
|
|
|
|
## Risks
|
|
- [Potential downside and impact]
|
|
|
|
## Rollback Plan
|
|
- Revert commit(s): [hash]
|
|
- Restore previous behavior with: [command]
|
|
|
|
## Testing
|
|
[How you tested this]
|
|
|
|
## Screenshots (if UI)
|
|
[Before/After images]
|
|
````
|
|
|
|
### After Submitting
|
|
|
|
- Respond to feedback promptly
|
|
- Make requested changes quickly
|
|
- Be grateful for reviews
|
|
- Don't argue, discuss
|
|
|
|
## Building Reputation
|
|
|
|
### The Contribution Ladder
|
|
|
|
```
|
|
Level 1: Documentation fixes
|
|
↓ (build familiarity)
|
|
Level 2: Small bug fixes
|
|
↓ (understand codebase)
|
|
Level 3: Feature contributions
|
|
↓ (trusted contributor)
|
|
Level 4: Maintainer status
|
|
```
|
|
|
|
### Consistency Over Volume
|
|
|
|
```
|
|
❌ 10 PRs in one week, then nothing
|
|
✅ 1-2 PRs per week, sustained
|
|
```
|
|
|
|
### Engage Beyond PRs
|
|
|
|
- Answer questions in issues
|
|
- Help triage bug reports
|
|
- Review others' PRs (if welcome)
|
|
- Join project Discord/Slack
|
|
|
|
## Common Mistakes
|
|
|
|
### Don't
|
|
|
|
- Submit drive-by PRs without context
|
|
- Argue with maintainers
|
|
- Ignore code style guidelines
|
|
- Make massive changes without discussion
|
|
- Ghost after submitting
|
|
|
|
### Do
|
|
|
|
- Start with small, focused PRs
|
|
- Follow project conventions exactly
|
|
- Communicate proactively
|
|
- Accept feedback gracefully
|
|
- Build relationships over time
|
|
|
|
## Workflow Template
|
|
|
|
```
|
|
Contribution Workflow:
|
|
- [ ] Find project with "good first issue"
|
|
- [ ] Read contribution guidelines
|
|
- [ ] Comment on issue to claim
|
|
- [ ] Fork and set up locally
|
|
- [ ] Make focused changes
|
|
- [ ] Run evidence loop (reproduce fail -> apply fix -> rerun same command pass)
|
|
- [ ] Add baseline vs fixed vs reference comparison
|
|
- [ ] Redact paths/secrets/internal hosts in logs and screenshots
|
|
- [ ] Test thoroughly
|
|
- [ ] Write clear PR description
|
|
- [ ] Respond to review feedback
|
|
- [ ] Celebrate when merged! 🎉
|
|
```
|
|
|
|
## Quick Reference
|
|
|
|
### GitHub CLI Commands
|
|
|
|
```bash
|
|
# Fork a repo
|
|
gh repo fork owner/repo --clone
|
|
|
|
# Create PR
|
|
gh pr create --title "feat(scope): ..." --body "..."
|
|
|
|
# Check PR status
|
|
gh pr status
|
|
|
|
# View project issues
|
|
gh issue list --repo owner/repo --label "good first issue" --state=open
|
|
```
|
|
|
|
### Commit Message Format
|
|
|
|
```
|
|
<type>(<scope>): <description>
|
|
|
|
[optional body]
|
|
|
|
[optional footer]
|
|
```
|
|
|
|
Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
|
|
|
|
## References
|
|
|
|
- `references/pr_checklist.md` - Complete PR quality checklist
|
|
- `references/project_evaluation.md` - How to evaluate projects
|
|
- `references/communication_templates.md` - Issue/PR templates
|