The idea

Having recently been entrusted with the task of reviewing the team’s pull requests, I realized that many things can go wrong in the process of merging branches into master if it is not handled with care. For example, it happens from time to time that changes are accidentally overwritten because someone edited an automatically generated file and forgot to forward the changes to the template from which the file is generated; or important changes get lost while resolving merge conflicts because the person resolving the conflict is not aware of the changes a colleague has made; at other times, a pull request waits to be merged into the master branch for too long (thus increasing the likelihood of merge conflicts) because someone merged another branch into it, which is not yet ready to be merged itself; or merging the PR results in a broken build because someone forgot to make sure there are no build errors in their branch. Such things just happen, and when they do, it takes a lot of time and effort to fix them.

So, being on the lookout for ways to improve the way we handle pull requests, we came up with a new idea: checklists! Checklists are already in use in many areas such as aviation, surgery or the building industry. So why not use them in our development process as well?

A brief history of checklists

Aviation checklists reach back as far as October 30, 1935, the day on which the US Army Air Corps held an aircraft competition in order to decide about the next generation of military bombers. Among the competitors was Boeing’s Model 299, which had outshone the other competitors at the preceding evaluations and was considered to be the sure winner. However, as the aircraft had taken off and started to climb into the sky, it suddenly stalled, turned on one wing and exploded.

The cause of this crash was attributed to a ‚pilot error‘. Apparently, the pilot, being unfamiliar with an aircraft that was considerably more complex than anything he had ever flown before, had neglected a crucial step before the take-off. Because of its complexity, the news declared the aircraft to be ‚too much airplane for one man to fly‘. Still, the army ordered a couple of the Boeing aircrafts and had their test pilots deliberate on what to do. And they came up with a pilot’s checklist with step-by-step checks for takeoff, flight, landing and taxiing.

This was the hour of birth for aviation checklists. Not even have checklist prevented countless plane crashes since then; they also have saved myriads of lives in surgeries, and helped builders schedule large-scale building projects and make sure that the resulting buildings do not crumble down because an individual missed some crucial point, just to name a few examples. With checklists, we have found a way to come to terms with tasks that are too complex for one mind alone to remember.

How to write a good checklist

Seeing that checklists can have such positive effects, the next question was how to write a good checklist for my own purpose.

The first important thing to know about checklists is that they are not intended to spell out every single step in minute detail. They are not intended to turn off your brain completely and substitute the thinking process. Rather, they assume that you are aware of what you are doing and simply want to remind you of the most critical steps. In order for a checklist to be actually used by people, it needs to be simple, short and precise. If it is vague, imprecise or too long, it will be more bothersome than helpful.

There are two different kinds of checklists: read-do lists and do-confirm lists. With the former, you carry out a task as you check it off. With the latter, you can carry out a task as you remember. In the end, you pause to run through the checklist and ensure you have not forgotten anything. Read-do lists should be employed when the order in which steps are carried out is of importance, or when a wrong step has unwanted consequences. Do-confirm lists, on the other hand, leave the people who use them more freedom to execute their task as they seem fit.

Checklists for branching and creating pull requests

With this in mind, I set out to write my own checklists. For a start, I decided to write one for creating new branches and one for creating pull requests.

The list for creating branches is a read-do list as errors here cannot easily be erased. It aims at decreasing merge conflicts and preventing the wrong branches to end up in your new branch:

checklist for branching

The list for creating pull requests is a do-confirm list that makes sure you have done what is in your power to minimize sources of errors and losses of code:

checklist for creating pull requests


We are going to try out these checklists in our team for the next couple of weeks. I am quite curious to see how they work and how they are accepted by the team members. Will the team members like using them? Will they consider them helpful? Will the lists fulfill their purpose and improve the process of handling pull requests? I will keep you informed about the result of this little experiment. If the checklists turn out to be successful, I am going to create more lists to use in other parts of our development process. With those steps off our minds, we can focus our brain-power on our most challenging task – producing good code.