How to ship your first pull request on a codebase you just joined

What should your first pull request actually change?

Something small, real, and in a place where being wrong is cheap and obvious. Good candidates share one trait: a clear definition of done that a reviewer can check without holding the whole system in their head.

• A bug with a reproducible case
• A missing test for behaviour that already exists
• A piece of documentation that was wrong when you followed it last week
• A small task someone on the team has already scoped

There is a pull in the opposite direction and it is worth naming. A first pull request feels like an audition, so the temptation is to pick something big enough to prove you were worth hiring. The problem is that nobody on the team knows yet whether they can trust your judgement, and a large change asks them to trust it a lot. Small is the faster way to earn that, not the humbler one.

Leave refactoring alone for now. Refactoring belongs in its own change, and there is a second reason to wait: you cannot yet tell the difference between code that is badly written and code that looks odd because it solves a problem you have not met. Those two things look identical from the outside. The only thing that separates them is context you do not have yet.

The same goes for anything that looks like tidying:

• Renaming things
• Reorganising folders
• Rewriting a pattern you have seen once
• Changing build or CI configuration

Back to the three ways of doing the same thing. Usually one is current, one is being migrated away from, and one is a dead end nobody removed. The dates in git blame will tell you more than the code will. If the newest usage is six months old and the oldest is from last week, you are looking at the migration running backwards, which is worth asking about before you copy either.

How do you know when your pull request is too big?

Open your own diff and read it as if someone else wrote it. Then ask what you would have to explain to make it make sense. If the answer is more than one thing, you have more than one pull request.

The most common version of this is a fix that grew:

That last row is the one people argue with. Fixing both feels efficient. It is not, because now your reviewer cannot approve one without accepting the other, and the simple change waits for the complicated one.

What should you read before writing any code?

Read the last twenty merged pull requests in the repository. It is the fastest way to learn how this team works, and it is more reliable than the contributing guide, which is usually out of date.

If you do not have repository access yet, that is the first thing to chase, ahead of any ticket. Waiting for access to appear on its own is the most common way to lose a week.

Twenty merged pull requests will tell you:

• How big changes usually are here
• How much detail descriptions carry
• Whether tests go in the same change
• Who reviews what, and who reviews quickly
• How direct the review tone is, so you can read your own feedback correctly
• How long things sit before being merged

All of it is context you would otherwise pick up by getting it wrong once.

Then read around the code you are about to touch rather than only the function itself. The tests near it show which behaviour is load-bearing. The CI config shows what will fail before a human sees it. The commit history on that file shows whether it is stable or has been changed four times this quarter, which changes how carefully you should tread.

One habit is worth building now: when something in the code looks wrong, assume there is a reason before assuming there is a mistake. Source code shows what the software does. It rarely shows why, and that reasoning usually survives only in git history and old descriptions, if it survives at all.

There is also a window here that closes. In your first weeks you can ask anything without it costing you anything, because nobody expects you to know. That licence runs out around the time people stop thinking of you as new, and the questions you saved up get more awkward to ask, not less.

How do you write a pull request description that gets acted on?

Start with one line saying specifically what the change does, written as an instruction, then a blank line, then the reasoning. Google's guidance on change descriptions recommends this shape so that someone scanning the history months later understands the change without opening it.

The same page collects real descriptions that fail. They give a reviewer nothing:

• "Fix bug"
• "Add patch"
• "Phase 1"

Here is the version that works, for a change you might plausibly make in your first fortnight:

Prevent duplicate submissions on the checkout form

The submit button stays active while the request is pending, so a second click can create another order. This disables the button until the request completes. Added a test for repeated clicks.

I followed the loading-state pattern used in the account form. Is that the right reference here?

Four things are happening there. The first line says what. The next says why the bug exists, which is the part that cannot be reconstructed from the diff. Then the validation, so the reviewer knows what has already been checked. Then the question.

That last line is the one that does the most work for you, and it is the one people leave out. Naming what you were unsure about turns a review from a correctness check into a conversation, and it makes it far more likely that someone explains the reasoning instead of just requesting a change. It also protects you: if the loading-state pattern was the wrong reference, you found that out in review rather than in three more pull requests built on the same assumption.

Saying you are unsure is not an admission that you should have known. In week two, it is the accurate description of your situation, and reviewers read it that way.

What do the review comments really tell you?

Less than you think, taken as a count. A long thread does not tell you the change was bad, and a short one does not tell you it was good. It might mean the reviewer is thorough, or that they have opinions about this file specifically, or that the area is genuinely tricky, or that they had twenty minutes and used them. Most comments on a first pull request are about conventions you had no way of knowing.

What is worth doing is separating what blocks the merge from what does not. If that is unclear, ask directly:

Which of these are blockers, and which can we handle in a follow-up?

It is a normal question, it is faster than guessing, and it tells you something about how the team works that you can apply next time.

Answer every comment, including the ones you are simply implementing, so the reviewer can see the thread is closed. When a comment does not make sense, ask what the underlying concern is rather than guessing at the fix. Getting a convention explained once is worth more than getting one line changed.

If a comment opens up something larger, the test is whether the change works correctly without it. If it does, put the larger thing in a follow-up. If the change is not correct without it, it belongs in this pull request no matter how much it grows, because a merged change that is known to be wrong is worse than a slow one.

The reviewer's side of this has its own logic, and KWAN's article on whether code review is worth it covers what an experienced reviewer is weighing when they read your diff.

Where KWAN fits in the first weeks

Whether shipping this little in week one is a problem is not a question you want to ask the person reviewing your code. Every KWANer works with a People Experience Partner, separate from anyone measuring delivery and usually met before day one. The team handles the technical side. The PEP is who you ask when the question is whether any of this is normal, and a nearshore engineer's first 30 days describes those weeks from that angle.

If that is the kind of start you want, our open roles are here.

Frequently asked questions

1. How long should you wait before opening your first pull request?

Days rather than weeks. Opening something small early gets you feedback on conventions while the cost of being wrong is still low. Waiting until you fully understand the system means learning the conventions the slow way, and usually in a bigger change.

2. Should your first pull request include tests?

Usually yes. A change that adds or alters logic should come with new or updated tests in the same change, so a reviewer can see what behaviour you are claiming. Check the last few merged pull requests to see what your team expects in practice.

3. Does a lot of review comments mean your pull request was bad?

No. The number of comments does not tell you whether a change was good, since it reflects the reviewer, the file and the time they had as much as the code. On a first pull request most comments are about conventions that are not written down anywhere.

4. What should you do if you disagree with a review comment?

Ask what the concern is before arguing the fix. On a codebase you just joined, an odd-looking request often reflects a constraint you have not met yet. If you still disagree after the explanation, say so plainly and let the reviewer decide.