Developers need more checklists. As a flight instructor I became accustomed to using checklists in a particular way, and I have begun carrying their benefits into my work with software.

Recently, the company I work for began transitioning to a git-based release process. Several of the developers, including myself, are new to git so we decided to transition in phases. We are currently in phase 1, where we use git in parallel with our old process. The idea is to get a good handle on git before we are depending on it to launch code to our production environment. During this phase there are a lot of steps required to launch a feature or bug fix.

In the old process we had 2 extra domains for each developer. One had the suffix ‘dev’ and the other ‘test’. We would develop on ‘dev’ and then copy the code to ‘test’ when it was ready for some testing. Pushing to production was simply a matter of copying the code from ‘test’ to the live site. This process worked well but as developers have joined the team it has become more difficult to merge code.

So this transitional phase contains the steps above with a few extra steps. Every developer runs git on their local machine and we publish our branches to Github when they are ready. Then we start a Pull Request, and ask for a code review from another developer, For quality assurance, a project manager does some final testing. Once these two tests are done the code is approved and can be merged into the master branch in git. This is where things are still disassociated. Merging to the master branch in git doesn’t get the code into the production environment. Instead, the developer who built the feature still manually copies the code in order to perform the final launch.

As you can see, there is a lot of room to forget something in this process. When I would make Pull Requests, I would sometimes forget to push my code to my ‘test’ domain. It needs to be on the ‘test’ domain because when I finish a feature and send it up to Github, I start the next feature and my ‘dev’ domain goes back to the state that the production domain is in. When the product manager goes to test the code it needs to be running on the ‘test’ domain. This can be a big deal, especially with a large feature that affects core functionality, because the product manager will spend a bunch of his time testing the product and writing a big list of bugs. Then when I am notified of these bugs I can see immediately that I forgot to copy my code over to ‘test’. It’s embarrassing and it wastes other people’s time.

How do we fix it?

In aviation, checklists are used constantly to ensure that flights are conducted safely. A typical small plane will have over a dozen checklists just to cover the normal procedures in a flight. On top of this, there can be many emergency checklists that cover procedures when something goes wrong.

As an example, here is the “Before Landing” checklist for a light 4 seat single engine plane.

 

You should notice right away that there are only a few items on here. It isn’t that hard to memorize 9 things, and most pilots who fly this plane memorize this list quickly. However, going through the checklist by memory only is the wrong thing to do. It is extremely unsafe and no serious pilot does it.

There are at least two big advantages to the checklist. First is the obvious advantage – every item in the procedure is taken care of. The second advantage is not so obvious. It is confidence. You don’t have to be nervous about forgetting something important before landing.

Without the checklist you would run through these items in your mind over and over trying to think of the one you are forgetting. I know the feeling from my early days of flying, when I didn’t have the best habits with checklists. Interestingly, that nervousness is the exact same feeling I used to get pushing code to production without a checklist.

If you used the checklist you made a mental note “Before Landing checklist complete”. If you use the checklist before pushing your code out you can feel confident that you did enough code review and testing, and that you didn’t miss a step in the push.

My current Pull Request Checklist is split into 4 sections:

Writing Test Cases

In this section I am building a set of questions to answer when testing. This is part of my process that I use to test the feature I am building. Note that the checklist is not the same as my set of test questions, which are more specific to the code in question.

Testing

I don’t pass this part of my checklist until all testing is done.

Code Review

This is a lighter version of a much larger code review checklist I used in the past.

Launch

These are the procedural steps required before the pull request.

Here are the full checklists

Writing Test Cases

o
• The feature performs its basic purpose.

o

• What does the user see before during and after using the feature?

o

• Is there any existing code that this fits into? Check for bugs there too.

o

• Have you reviewed the whole ui including all wording?

o

• Have you covered all special cases?

Testing

o
• Have you tested all cases?

o

• Have you considered any new cases that should be included in the test?

Code Review

o
• Remove all debugging statements.

o

• Check variables and syntax.

o

• Check logic.

o

• Clean up whitespace.

o

• Check security, especially for variables on their way to the database.

Launch

o
• Commit latest changes.

o

• Push to test server.

o

• Perform final test.

o

• Pull Request.

 

---

Try it out

A code review checklist is the simplest place to start. Your goal is to add checklist items that may be appropriate sometimes. Take a look at the Before Landing checklist again. See the “Air conditioner – OFF” item? The plane I fly doesn’t have an air conditioner, so I read that item, remind myself that there is no air conditioner, and move on. My Code Review checklist has a security item which works the same way. Sometimes the feature I am building is just a change of wording in the UI, with absolutely no security implications, but I read the item, make a mental note that it doesn’t apply, and move on.

If you don’t already use some kind of checklist I encourage you to try it out. You should find that your are more confident in your code and your process.