Issues & Pull Requests
The Core Workflow
Issues and PRs are the primary communication mechanisms in open source. Master them, and you master open source contribution.
The Complete Cycle
The Two Pillars
Issue & PR Lifecycle
┌─────────────────────────────────────────────────────────────────────────────┐
│ ISSUE → PR → MERGE TIMELINE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Day 0 Day 1-3 Day 3-7 Day 7-14 Day 14-30 │
│ ═════ ════════ ═══════ ═════════ ═════════ │
│ │ │ │ │ │ │
│ │ Issue │ Triage & │ Development │ Code Review │ Merge │
│ │ Created │ Assignment │ & Testing │ & Iteration │ or Close │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ Open Acknowledged PR Opened Changes Made Resolution │
│ │
│ ◄──────────────── Typical: 2-4 weeks for first contribution ─────────────►│
│ │
└─────────────────────────────────────────────────────────────────────────────┘Success Metrics
What Makes Issues Get Addressed
| Factor | Impact | Why It Matters |
|---|---|---|
| Clear reproduction steps | 🔥🔥🔥 | Makes the problem actionable |
| Recent activity | 🔥🔥 | Shows it's still relevant |
| Affects many users | 🔥🔥🔥 | Higher priority |
| Has error logs | 🔥🔥 | Easier to debug |
| Respectful tone | 🔥 | People want to help |
What Makes PRs Get Merged
| Factor | Impact | Why It Matters |
|---|---|---|
| Small scope | 🔥🔥🔥 | Easier to review |
| Tests included | 🔥🔥🔥 | Reduces risk |
| Good description | 🔥🔥 | Context for reviewers |
| Follows conventions | 🔥🔥 | Maintainable code |
| Responsive to feedback | 🔥🔥🔥 | Shows professionalism |
Quality Spectrum
Section Overview
Raising Good Issues
Learn to write bug reports and feature requests that maintainers actually want to read
Bug vs Feature
Know the difference and use the right template for each
Writing High-Quality PRs
Small, focused, tested changes that reviewers love
PR Templates
The anatomy of a perfect PR description
Code Review Response
How to handle feedback professionally and efficiently
Handling Rejection
Not all PRs merge. Learn to fail gracefully and improve
Iterating on Feedback
Speed up the review cycle with smart responses
Closing PRs
How to clean up and move forward
Common Mistakes
Issue Mistakes
These Get Issues Closed Without Action
- "It doesn't work" (no details)
- Asking for ETAs or demanding fixes
- Not checking if already reported
- Missing reproduction steps
- Opening issues that belong in discussions
PR Mistakes
These Get PRs Ignored or Rejected
- No description or "small fix" without context
- Massive diffs touching unrelated files
- No tests when tests are expected
- Ignoring CI failures
- Being defensive about feedback
Time Expectations
Reality check:
- First response to issue: 1-3 days (sometimes 1-2 weeks)
- First PR review: 2-7 days (sometimes longer)
- Total time to merge first PR: 2-6 weeks average
The Mindset Shift
❌ Wrong Mindset
"I'll open an issue and get an immediate response"
"My PR is perfect, reviewers are nitpicking"
"I'll make one huge PR with all my changes"
"If my PR doesn't merge, the maintainers are biased"✅ Right Mindset
"I'll provide all the info maintainers need upfront"
"Reviews improve my code and teach me conventions"
"I'll make small PRs that are easy to review"
"If my PR doesn't merge, I'll learn why and improve"Quick Reference
Issue Checklist
- Searched for existing issues
- Clear, descriptive title
- Reproducible steps provided
- Environment details included
- Logs/screenshots attached
- Respectful, professional tone
PR Checklist
- Linked to an issue
- Small, focused changes
- Tests added/updated
- CI passing
- Good PR description
- Follows project conventions
Remember: Issues and PRs are conversations, not transactions. Approach them with respect, clarity, and patience.