Submitting Pull Requests

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.

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.

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.

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.

It's crucial to acknowledge feedback constructively. Option 1 is too dismissive; option 3 demonstrates engagement and a willingness to collaborate on solutions. Option 4 misrepresents responsibility - accessibility considerations are often relevant in frontend development regardless of backend involvement. Choosing option 2 avoids the issue, but doesn't progress the conversation.

The maintainer is requesting *reproducible steps*. A good response clarifies what information they require. Option 1 assumes the description was sufficient, which may not be true. Options 2 and 4 are unhelpful and avoid addressing the request. Asking for specifics demonstrates you're trying to understand their needs.

A good response focuses on investigation and potential root causes. Simply stating you followed best practices isn't sufficient. Option 2 deflects responsibility unfairly. Options 1 and 4 downplay the severity and avoid addressing the underlying problem. Identifying specific areas to investigate shows a proactive approach.

Addressing potential issues proactively is key. Simply saying you'll fix it later isn't helpful. Option 2 is an unacceptable response – race conditions are serious and should be addressed directly. Options 1 and 4 demonstrate a lack of urgency and disregard for the maintainer's concerns. Scheduling a call allows for collaborative problem-solving.

Understanding validation requirements is essential. Ignoring the error or assuming the documentation is incorrect could lead to further problems. Option 1 is completely unacceptable. While option 4 expresses frustration, a productive response involves clarifying the validation rules and ensuring your code adheres to them.