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
Ready to Master the Workflow?
Let's start with the foundation:
âĄī¸ How to Raise a Good Issue â
Remember: Issues and PRs are conversations, not transactions. Approach them with respect, clarity, and patience.