4 exercises — PR descriptions, first-time contributor intros, responding to context requests, and handling architecture feedback.
0 / 4 completed
PR description structure: What / Why / How / How to test
What — one sentence describing the change with a file/function reference
Why — the root cause or motivation + issue link
How — the implementation approach in plain language
How to test — command to run, new test location, manual test recipe
On architecture feedback — ask for the evidence before agreeing; defer to the maintainer's judgment
1 / 4
You've implemented a fix for issue #142 in the `axios-retry` library. Which PR title and description opening is most effective?
Option C demonstrates a professional PR description:
Title structure — `fix: [what changed] — [why it mattered] (#issue)`: "retry count resets to 0 on network timeout instead of preserving state (#142)" — reads like a sentence describing the broken behaviour that is now fixed. A maintainer who reads only the title understands the scope of the change.
What / Why / How / How to test — the four sections every PR needs: 1. What — one sentence describing the change with file/function reference. Not a summary of the diff — the diff is available. This is the intent behind the diff. 2. Why — links the issue AND explains the root cause ("the root cause: this.retryCount = 0 was called in the timeout handler"). This tells the maintainer you understand the problem, not just patched a symptom. 3. How — the approach to the fix, in plain language. For a simple fix, two sentences. This lets the maintainer understand the change before reading the code. 4. How to test — the most important section for fast merges: (a) automated test command, (b) pointer to the new test by line number, (c) manual test recipe. The reviewer should be able to verify your fix in 3 minutes.
Why "Fixed #142" is not enough: It does close the issue automatically on merge (GitHub feature) but tells the reviewer nothing. They still have to read the diff and figure out what you changed, why, and how to verify it.
2 / 4
You're contributing to a Python CLI tool for the first time. You want to introduce yourself appropriately in your first PR comment. Which message is best?
Option C is the ideal first-time contributor introduction:
Why this framing works: 1. "First-time contributor to this project" — not "I'm new to programming" — precise and neutral. Sets appropriate expectations without asking for special treatment. 2. "I've read CONTRIBUTING.md" — the single most reassuring thing a new contributor can say. Many first PRs fail because the contributor didn't read the contribution guide. Saying you did signals respect for the maintainer's time. 3. "Tried to follow the existing code style and test patterns I found in tests/cli_test.py" — shows you looked at existing code, not just wrote what felt right to you. Naming the specific file you used as a model demonstrates genuine effort. 4. "Happy to adjust anything" — makes further collaboration explicitly welcome. Removes the fear that feedback will cause defensiveness. 5. "Left an inline comment on line 47" — flags the complicated part proactively, before the reviewer discovers it and wonders if you noticed. This is expert behaviour.
Why the empathy-seeking opening ("please be kind") is counterproductive: It creates an awkward dynamic — the maintainer now feels responsible for your feelings. Professional contributors assume feedback is about the code, not about them. Starting with "please be kind" signals you might not handle feedback well.
Why "5 years of experience" is irrelevant here: The code speaks for itself. Mentioning your experience before the maintainer has seen your code reads as compensating for something — and can come across as dismissive of the project's standards.
3 / 4
Your PR fixes a clearly broken test. But in the PR description, you write "Closes #88" and nothing else. The maintainer asks: "Can you add context to the PR description?" What do you write?
Option C is the correct response to a "can you add context?" comment:
What makes this response effective: 1. Quick acknowledgement without excessive apology — "apologies for the thin description" — addresses it and moves on 2. What — names the specific file and test, names the renamed key, and cites the PR that introduced the rename (#83). The maintainer can go directly to that PR to verify the history. 3. Why the test was broken — explains the timeline (rename was intentional, test update was missed). Without this, the maintainer might wonder if the rename itself was wrong. 4. Risk assessment — "test-only change, no production code modified" — this is the question every maintainer has. Answering it proactively in the PR description is faster than having them ask. 5. Evidence of correctness — "running pytest tests/config_test.py now passes; previously failed with KeyError" — shows the fix works, not just that you made changes.
The context-request pattern: When a maintainer asks for more context, they're telling you what information they need to feel confident merging. The correct response is to provide exactly that — not to write "I'll do better next time" (which leaves the current PR without the needed context). Always add the context to the PR description itself, not just as a comment reply — future readers will see the description, not the comment thread.
Risk assessment in PRs: "Test-only change" vs "changes prod code" vs "changes public API" are the three risk tiers. Telling the maintainer which tier your PR falls in saves them the work of figuring it out.
4 / 4
A maintainer reviews your PR and says: "The implementation approach here is going to cause issues — we tried this pattern in 2021 and had to revert it because of X." How do you respond?
Option C is the collaborative response to an architecture concern from a maintainer:
What makes it effective: 1. "Thanks for the context — I hadn't found that in the history" — acknowledges the information as genuinely new and valuable, not defensive 2. "Could you point me to the issue or commit?" — asks for the evidence before agreeing or disagreeing. This is intellectually honest and practically useful — the history might reveal a nuance that changes your position 3. Acknowledges the definitive case — "if it's exactly the same pattern, I'll rewrite it immediately" — makes a concrete commitment to change if the concern applies 4. Raises the possibility of a difference — "if there's a meaningful architectural difference" — you're allowed to think your approach is different from the failed 2021 one. But the framing is a question, not a claim: "it might be worth a quick discussion" 5. "I defer to your judgment on this" — decisive close. States that you will ultimately follow the maintainer's decision. This is important — open source maintainers need to trust that contributors won't argue indefinitely over one PR
Why "That was 2021, things have changed" is harmful: It dismisses the maintainer's experience without evidence. Even if the codebase has changed, they were there when the problem happened and you weren't. Dismissing their experience is the fastest way to have your PR closed without merge.
The "I defer to your judgment" principle: In someone else's project, maintainers have the final word on architecture. Your job is to contribute your best understanding while respecting that they're more familiar with the project's history and constraints than you are.