Simple Guide for Better Pull Requests

Why are pull requests needed

A book is not just the work of the author alone. The author gets feedback and the story gets edited multiple times before it becomes the book you’re holding in your hand.

Making a pull request is putting your code through a similar process. The goal is for the code to not only be functional, but also well-documented and clean.

What to NEVER do

Everyone on the team will take turns reviewing each other’s work. Nothing frustrates a reviewer more than seeing a huge pull request with just one commit that reads “update feature.”

We don’t want to make our team slog through huge changes. Reviewers take time out of their days that could have been spent on developing to help each other out. We need to respect that time. Make it as easy as possible to understand what work has been done.

Three simple guidelines

Keep the pull request small (if possible)

Whenever possible, break down a large project into smaller chunks. If the project were to build a new site from scratch, I wouldn’t recommend making a pull request only when you’re done with the site.

Your team won’t be able to give you as thorough of a review because of the sheer amount of code to go through.

If I were building a site from scratch, I would start the project as:

1. Set up a bare site with server
2. Create routes for pages
3. Create a shared layout for the pages
4. Style the menu in the shared layout
   ...

Each step would be its own pull request. Not only does a smaller pull request make it easier for the team to review, it also helps you practice breaking down large projects into smaller ones.

Write clear commit messages

Think of your commit history as an instruction manual for the code reviewers. They’re following it to understand the purpose and scope of the work you’ve done.

If you’re putting a bench together, how helpful would it be if the instructions you got were: 1. Build bench and 2. Fix instability?

Improving how I wrote my commit messages also ended up improving my planning skills. Before I had to break down a large project into mini projects. Now that chunk gets broken down even more into small, actionable steps.

Improving my commit messages also improved my planning skills. I already broke down the large project into mini projects. Now they get broken down even more into small, actionable steps.

When my commit history used to look like:

// Vague commit messages
- Add video player
- Fix playback

It now gets broken down into:

// Clear commit messages
- Install video player
- Add demo video to page
- Style player controls
- Add missing param to fix playback

Now the team can go through each commit and understand right away what was changed and why. This saves the reviewers time going through the code and your work can shipped to production sooner. Win-win for everyone.

Be open to feedback

Sharing code can be scary. You’re putting your work out there for everyone to see.Sometimes my imposter syndrome still strikes and I worry that someone will “find me out.”

What helps is remembering the main purpose of a team is to help each other grow. To note where our weaknesses lie. To improve our work. To be proud of what features go out to users.

Pull requests aren’t meant to be roadblocks, but rather learning opportunities.

If you ever have the misfortune of someone bullying you into approving requests because he tells you he knows better, the problem is with the person and not the process. Someone else may have more years of experience, but that doesn’t mean he or she knows everything. What sets the best developers apart is the drive to improving themselves.