Common Mistakes Developers Make in Their First Pull Request

Your first pull request feels a bit like a job interview you volunteered for. You have a branch, a diff, and a quiet hope that nobody notices anything odd. Then a maintainer leaves eleven comments, half of them about formatting, and you start wondering what you did wrong. Usually, nothing serious. Most first-PR friction comes from a handful of predictable habits, and all of them are fixable in an afternoon.

One pull request, several unrelated changes

Reviewers read diffs the way people read maps: they need a route, not a continent. A pull request that fixes a bug, renames a module, bumps a dependency and reformats three unrelated files is technically one change set and practically four. The reviewer cannot tell which line is load-bearing, so they either ask a dozen questions or approve without reading closely.

Keep one logical change per pull request. If you need to refactor before you can add the feature, land the refactor on its own and describe it as no behavior change. That phrase is a gift to a reviewer: it tells them they can skim for structure instead of hunting for bugs.

Splitting a large change without losing your mind

1. Land mechanical work first: formatting, renames, moving files. Keep it boring.
2. Add the failing test, or the test harness the change needs, in its own small PR.
3. Add the behavior in the smallest diff that passes that test.
4. If you stacked branches, say so in the description and name the base branch.

A 900-line diff is not a badge. If half of it is a rename your editor did automatically, split it out.

Tests that never get written, or never get run

Not every project wants a test for every change, and a one-line typo fix rarely needs one. What maintainers do want is evidence that you checked your work: a unit test, or three lines in the description naming the command you ran and the output you saw.

The cheapest useful test is the one that fails before your change and passes after. Write it in that order when you can. It proves the test is actually testing something, and it protects the function the next time someone else edits it.

When a test is genuinely impractical

Say so, and offer the closest alternative: manual steps, a small script, a screenshot of the output. "Not tested" on its own reads as "not considered," and silence about testing reads the same way.

Commit messages that say nothing

"fix", "wip", "changes", "asdf", "address review" — every maintainer has seen them. They are not lazy so much as rushed, written at the moment you thought you were finished rather than the moment someone else has to read them.

A commit message has two jobs: label the change, and explain why it exists. The subject can be short and imperative. The body, where most people stop, carries the reasoning the diff cannot show.

cache: compare key hashes when validating entries

Renaming a config key left stale entries in the cache, so users saw the old value until restart. Compare the hash rather than the key name so a rename invalidates correctly.

If your project squashes everything on merge, good commits still matter to you: they make git bisect usable, they let a reviewer read your branch in order, and they save you when you need to revert one piece next month.

Ignoring how the project already does things

Every repository has a personality. Indentation width, whether tests live beside the code or in a separate tree, how changelogs are written, whether commits need a sign-off. None of it is secret, and none of it is worth relitigating in your first PR.

• Read CONTRIBUTING.md and the pull request template before you write code, not after.
• Run the formatter and the linter the project configures. If it ships a hook, install it.
• Look at five recently merged pull requests. That is the real house style, whatever the docs claim.
• Do not reformat lines you did not otherwise touch. It hides your change and creates conflicts for everyone behind you.

If a convention seems wrong, open a separate issue about it. Arguing style inside a bug-fix PR rarely ends well.

A description that leaves the reviewer guessing

The pull request body is not paperwork. It is the only place where the context of your change exists, and most reviewers read it before they read your code.

What a useful description contains

• One or two sentences on what the change does.
• Why now: the issue number, the bug report, the user-visible symptom.
• How you tested it, with the commands and the output you saw.
• Anything you are unsure about, phrased as a question rather than hidden.
• Before-and-after output for anything visible.

Keep it short enough to read in a minute. A wall of text gets skimmed, which is the opposite of what you want.

Treating review comments as a verdict

Feedback on a pull request is a conversation about code, not a score on your ability. That is easier to say than to feel at eleven at night, but it changes how you respond.

When you agree, fix it and reply briefly. When you disagree, explain your reasoning in a sentence or two and ask a question. A reviewer often knows something you don't: a platform quirk, a downstream consumer, a decision made two years ago that looks arbitrary now. Asking why is faster than rewriting.

Reset your expectations on timing, too. A day or two of silence is normal, especially on projects run by volunteers. After a week, one polite comment on the PR is reasonable.

Before you press "Create pull request"

None of this requires seniority, only a few extra minutes. Run through this list and your first pull request will read like it came from someone who has done it before.

• The diff does one thing, and you can describe that thing in one sentence.
• The formatter, linter and test suite have been run locally.
• Commit messages explain the why, not just the what.
• The description covers what changed, why, and how it was tested.
• Unrelated cleanups are parked on a separate branch.
• You have read the contributing guide and skimmed recent merges.

Maintainers are not looking for perfection. They are looking for a change they can understand, verify and merge without a twenty-message thread. Give them that, and the second pull request is much easier than the first.

Photo: Christina Morillo / Pexels