The Pull Request Checklist for Startups

Bytebase
Bytebase
Jan 15 · 4 min read
The Pull Request Checklist for startups.

Startups that have an effective Pull Request (PR) process can ship features faster and with higher-quality code.

The key to an effective PR process for startups is to keep items small and decide on a lightweight guideline for describing what the PR introduces.

Here we’ll go over what we’ve found works best at Bytebase.

Pull Requests (PRs) should be short and meaningful.

Short PRs lead to higher-quality code.

Short PRs lead to higher quality code because short PRs are easier to review. Instead of skimming through endless diffs, a reviewer is able to more thoroughly review a small change, making it more likely that any potential issues are identified.

Short PRs lead to faster delivery of features.

Short PRs also lead to faster delivery of features because they keep the team in a good rhythm of shipping and make it less likely that one person’s work will block another’s. A PR that makes a small change is less likely to interfere with a small change that another teammate is working on.

There is such a thing as “too short.”

A PR that isn’t introducing meaningful functionality is too short. Meaningful functionality includes a complete change to one layer of your system. This might be a Data Model change, an API change, or a UI change.

At Bytebase, we keep PRs short by breaking down our tasks into small shippable pieces.

Break tasks into Small Shippable Pieces.

Small shippable pieces are non-breaking chunks of code that, in aggregate, create a feature.

Let’s see this in action.

Suppose I’m writing a blog application and have a task:

A reader can see the author of a blog post below the title of the post.

Rather than coding this task all at once, and putting up a big PR, I break the task down into small shippable pieces. I then submit the code changes for each piece in a different PR:

PR#1: Add author field to the Blog Post model.

PR #2: Add API endpoint that exposes author details for a Blog Post.

PR #3: Update frontend to show Blog Post author.

Note that these PRs need to be shipped sequentially, but #1 can be shipped without the others, and #2 can be shipped without #3.

Use a Lightweight PR Guideline

Now that we’ve broken down our task into small PRs, we can try to follow a consistent structure in our PR description to provide relevant details for the reviewer and for future reference.

At Bytebase, our PR description includes:

  • What changed.
  • Any questions for the reviewer.
  • Any next steps to do in this thread of work.
  • What you tested manually.
  • Screenshots if UI is impacted.

Using this guideline, let’s see how our PRs look for our task above.

PR#1: Add author field to the Blog Post model.

This PR impact the database. We specify what changed, what our next chunks of work will be, and what we manually verified.

PR#1: Add author field to the Blog Post model.

PR #2: Add API endpoint that exposes author details for a Blog Post.

This PR builds on the first by exposing the author details in a new API endpoint. We again give an overview of what changed, next steps, and what we manually verified.

If we had a question, for example, about the limitation of our API design, we’d include a “Questions” section below “What Changed.”

PR #2: Add API endpoint that exposes author details for a Blog Post.

PR #3: Update frontend to show Blog Post author.

This final PR builds on the first two by displaying the author of the blog post in the UI. We include relevant screenshots of our UI changes.

PR #3: Update frontend to show Blog Post author.

By keeping our PRs short and following an informal template, we make our PRs easier to review. This helps us write better quality code and ship faster.

Thanks for reading!

Bytebase, the byte-size knowledge base.

Bytebase is a web app that helps engineering teams share knowledge better. Everything in Bytebase is a “byte” — a short chunk of information. Bytes can be grouped together and organized, using the same principles engineers use to organize their code.

Check us out at bytebase.io or email me with subject line ‘Builder’ for access.

Bytebase

Written by

Bytebase

This is the official blog of Bytebase — the byte-size knowledge base.

More From Medium

More from Bytebase

Related reads

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade