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 #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 #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.
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.
