What a postmortem could have done to help
During October of 2020, CircleCI hosted Orbtoberfest alongside Hacktoberfest, which is a month-long event encouraging contributions to open source projects. CircleCI offered two different challenges, both of which are viable ways of participating in Orbtoberfest. In the first week of October, I had planned to complete one of the challenges within a few days by adapting an existing project for a narrower use case. While projects don't usually go according to plan, there were a few major problems I experienced that led to pronounced difficulties over the duration of the project.
In hindsight, one or more serious but informal postmortem(s) may have been able to address the issues in a much more timely fashion. While this article covers what the postmortem for a particular incident might have looked like, five months have passed since then. Over time, specific details have been forgotten, but some distance from the moment helps with clarity. This trade-off makes backfilling postmortems a useful exercise. Lots of information on how to write a postmortem and recover from an incident is available, and I will start by filling out the template for a few cases.
Postmortem I: Unable to setup the development environment
Overview: On the first day of the project, I was unable to install the CircleCI CLI . Code was thrown over the fence in lieu of running and testing on local machine.
What Happened: A straightforward way of installing the CLI was not available at the time. Instead of running code on local, the code was deployed in order to examine the results in the CircleCI dashboard via a second repository implementing the orb I authored.
Root Causes: Installing the CircleCI CLI would have established a faster and smoother workflow.
Resolution: Prioritize the installation of the CircleCI CLI
Postmortem II: Was not familiar with the versioning system used by CircleCI's registry
Overview: My workflow involved testing in production, but the first pushes to GitHub did not trigger the tests because CircleCI's versioning convention was not followed.
What Happened: Initial pull requests did not conform to the expected title format.
For example, to release the first major public version of your orb from the alpha branch, your pull request may be titled [semver:major] first orb release.
Root Causes: A lack of familiarity with CircleCI's orb authoring process led to a slower course correction.
Resolution: Isolate tasks to distribute cognitive load, i.e., make pull requests for the purpose of triggering the publishing process.
These are some examples of postmortems that could have been written during the software development process. If prompt action had been taken to correct the issues listed, the software would have been faster to write. The code as it was written has been included below.
Sources:
- The orb
- The code implementing orb