George Claghorn

Things you are allowed to do when reviewing a pull request

Think it over. Read the PR completely, understand it as best you can, then put it away. Work on something else for a few hours. Go for a walk. Do laundry. Sleep on it, even. Let it slosh around in your mind. Return to it when your gut has settled.

Don’t hold up your colleague’s work forever. Tell them if you’re going to need more than a few hours. Don’t completely disregard your gut instincts, either. If something changes—you feel differently than you did at first, or something muddy becomes clear—it can be useful to ask why. But don’t be afraid to take your time.

Experiment. Check out the branch locally. Click around.

Try the changes you want to suggest. You may figure out why the author didn’t take the approach you have in mind in the first place, or you may find an even better way.

Poke at the parts of the code that confuse you. They may reveal themselves to you, or you may find a way to clarify them. “Why do we need this?” Rip it out and see what happens. “Does this break if…?” Give it a shot.

Read it many times. Read the changes all the way through once. Draft comments for any questions that pop into your head. When you’re finished, go back and delete the questions that were answered later in the PR.

Writers sometimes change fonts to read their work fresh. Read through the changes in your web browser, then read through them again in your editor of choice. Switch themes, switch fonts, switch between dark and light mode. What stands out?