Developer Checklist
Couple weeks ago I finished reading the Checklist Manifesto and guess what? I did my own checklist.
I was familiar with checklists because my curiosity about aviation and human factors in high reliable organizations, this book was just the little push I needed to making one myself.
A little more about checklists
A checklist is not a step by step procedure and it shouldn't be comprehensive, it's not a manual. The point is to help experts to not forget simple steps that have great importance. Checklists are only good if they are used and prevent mistakes. That's why they have to be simple and focus on important steps.
Another characteristic is pause points. Some checklists will have a big bold title (like the one above) telling you when to use it and that's a "pause point". Some tasks will have several pause points, here's some examples of pause points in aviation:
- Before push back
- Before take off
- After take off
- Before landing
- After landing
Checklists are divided in two types, one known as READ-DO and another DO-CONFIRM. In short the READ-DO type you read item by item while executing each item. For the DO-CONFIRM you do all steps by memory and confirm these steps against the checklist.
More information about checklists you can find in the book and if you feel like trying do your own checklist also check Project Check website.
What the left terms mean
- CI
- Continuous Integration - your build system, i.e. ThoughtWorks Go, Jenkis, Team City...
- Upstream
- The code repository you're working on, i.e. Github, SVN, Bitbucket...
- Tests
- Your tests, basically the unit tests.
- Files
- The files you are working or are part of your change.
- Commit mgs
- The message you write on your commits, also known as commit log.
Understanding this checklist
Before I started this checklist I asked myself "where did I and my colleagues made more mistakes?" Where we usually have to follow certain steps and we end up making a mistake? My conclusion was: when we check-in code into repository and that was my pause point.
BEFORE PUSH in capital letters sets the time when this checklist fit. This is a little biased to distributed version control systems, but checklists are encouraged to be changed, so if you use SVN you can change the pause point to BEFORE COMMIT.
This is a DO-CONFIRM checklist. The items are simple and well known for software developers, so just saying "CI green." is very similar to "Gear down, three greens." (When pilots say "Gear down.", a lever should be moved and there's three lights on it. "Three greens" means that all three landing gears are down and locked.)
Note that this checklist has the style of aviation checklists, the user will be familiar with the acronyms and the actions/states they should be in.
The order and the purpose of each item
1. CI...GREEN
Before sending the code you will update, this step is to avoid updating/pulling from a broken build (unless you intend to fix it). If you pull from a broken build you might break your current work. Instead, you might choose to keep working until the build is fixed.
2. Upstream...PULL/UPDATE
Most version control systems will not check-in code if conflicts show up, but that's not the thing you are focused on. Updating your code before checking-in is considered a good practice, gives you the opportunity to see if other team members changes will play well with yours and sometimes you need to make further changes to accommodate the others.
3. Tests...FULL SET - GREEN
During your work usually you run just a small set of tests to keep things fast. Before sending your changes and specially because you just pulled changes from others, it's good to check if all the tests are green.
4. Files...ADDED/STASHED
This step is to check is the files you about to be check-in are the ones part of your change. It's very common check-in files that are not related to your change.
5. Commit msg...REVIEWED
Most companies have hooks on version control to relate the commit with a ticket/story. People tend to check-in wrong identifiers, wrong messages and similar mistakes.
6. CI...GREEN
After all the checks above the build might be broken (other team member checked-in code) or potentially brake if is still running. This step is for you double check if sending the files is safe.
Last notes
I plan to expand this work with other checklists, I believe there's space for it and enough pause points in software development where we can benefit from checklists. If you have ideas or want check out the code and the PDF go to GitHub.