Writing Pull Requests That Get Merged

🔄 Recall Bridge: In the previous lesson, you mastered the Git workflow — fork, branch, commit, push. Your code is ready. Now let’s make sure your pull request gets the attention and merge it deserves.

A pull request is more than a code delivery mechanism — it’s a communication document. The best PRs make the reviewer’s job easy by explaining what, why, and how to verify. Maintainers who review dozens of PRs per week can tell immediately whether a contributor took the time to write a good description.

The PR Description Template

AI prompt to draft your PR description:

I’m opening a pull request. Here are my changes: [PASTE YOUR DIFF OR DESCRIBE]. The issue I’m addressing: [ISSUE DESCRIPTION OR NUMBER]. Draft a PR description with: (1) A clear title under 72 characters, (2) A summary of what changed and why, (3) How to test the change, (4) Any trade-offs or alternatives you considered. Match the style of recent merged PRs in this project.

PR description structure:

## What

Brief description of the change (1-2 sentences).

## Why

The problem this solves, linking to the issue.
Fixes #42.

## How

Technical approach — what you changed and why you chose this approach.

## Testing

Steps to verify the change works:
1. Run `npm test` — all existing tests pass
2. New test in `tests/parseDate.test.ts` covers timezone offsets
3. Manual test: `parseDate("2026-01-15T10:30:00+05:30")` returns correct Date

## Notes

Any context the reviewer should know — alternatives considered,
limitations, or follow-up work needed.

Self-Review Before Submitting

Before opening your PR, review your own changes as if you were the maintainer.

AI prompt for self-review:

Review this diff as if you’re a maintainer of this open source project. Check for: (1) Code that doesn’t match the project’s patterns or conventions, (2) Missing error handling that other similar code includes, (3) Edge cases that aren’t covered, (4) Unnecessary changes (whitespace, formatting) mixed in with functional changes, (5) Missing or inadequate test coverage. Be strict — it’s better to catch issues now than have a maintainer point them out.

Self-review checklist:

Common Reasons PRs Get Rejected

Responding to Review Feedback

Review feedback is the most valuable part of open source contribution. Maintainers are teaching you their codebase and engineering standards for free.

Types of feedback and how to respond:

AI prompt for understanding feedback:

A maintainer left this review comment on my PR: “[PASTE COMMENT]”. Help me: (1) Understand exactly what they’re asking for, (2) Draft a professional response, (3) Show me the code change they want. If I disagree with the suggestion, help me articulate why in a respectful way.

✅ Quick Check: You open a PR and the maintainer responds: “Thanks for the contribution! Could you rebase on the latest main? There’s a conflict.” What do they want you to do? (Answer: Your PR branch has diverged from the project’s main branch. Run: git fetch upstream, git rebase upstream/main, resolve any conflicts, then force-push your branch with git push --force-with-lease origin your-branch. The --force-with-lease flag is safer than --force because it checks that you haven’t accidentally overwritten someone else’s changes.)

PR Size Guidelines

Smaller PRs get reviewed faster and merged more often:

If your change is large, consider splitting it into multiple PRs that can be reviewed independently.

Key Takeaways

• A PR description is a communication document that should explain what changed, why, and how to verify — the code shows the what, but reviewers need the why and testing steps to evaluate your approach efficiently
• Self-review your changes before submitting using AI as a strict reviewer — catching style mismatches, missing tests, and debugging artifacts before a maintainer points them out shows professionalism and respects the reviewer’s time
• Respond to review feedback promptly and graciously — thank reviewers for catching issues, explain your reasoning when asked, and defer to maintainers on design decisions; how you handle feedback determines whether you’re welcomed back for future contributions

Up Next

In the next lesson, you’ll learn about contributions that don’t require writing application code — documentation improvements, issue triage, and translation work that every project needs.