ADRCTL, a modernized tool for managing Architecture Decision Records

While working on my upcoming book, Getting Started with Architecture Decision Records (ADRs), I demonstrated Nat Pryce’s adr-tools tooling. Nat’s tool is truly excellent and I’ve been using it for years. It’s a Bash shell script that can be used to quickly create and maintain ADRs in a Git repository.

As my needs evolved, I found a little place here and another place there where adr-tools didn’t quite align with my needs. For example, adr-tools has a shell script driver plus a bunch of libraries for individual commands. Don’t get me wrong, I love a modular, extensible approach! On the other hand, it meant having to clone or track a small repository of files, not just a single script.

The filenames adr-tools used for ADRs worked well until I encountered a project whose naming convention conflicted with them.

So, a new tool was born: adrctl!

My adrctl tool picks up right where adr-tools left off. In fact, adrctl retains the same user-facing API as adr-tools. You can literally download adrctl.bash, make it executable, and alias or symlink to it so all of your existing muscle memory will work the same.

While adr-tools is distributed as a repository, adrctl is distributed as a single shell script. One file. The repository hosting adrctl uses a release process with consistent, uniform URLs. Each release is immutable and includes cryptographic attestation to the build process. Each release includes a SHA-256 hash that can be used to verify what you’re downloading.

Each release comes with three versions of the adrctl script:

• adrctl.dev.bash: the full version, complete with development documentation
• adrctl.bash: same script but with development comments removed
• adrctl.min.bash: unnecessary comments and whitespace characters removed

There are SHA-256 hashes for each of those files as well.

Just because adrctl is distributed as a single shell script doesn’t mean that it discards a modular development approach. Just like with Bootstrap, adrctl is developed using a modular, plugin-like approach with automatic discovery. Adding a new command to adrctl is done by adding another plugin to the repository and rebuilding adrctl.

There are dozens of unit and regression tests run before any changes are merged into the repository. The entire test suite is run before every release; as a result, each release has gone through – literally – hundreds of tests before being cut.

All of the dependencies used to build adrctl are documented in a file named dependencies.txt. Each dependency is pinned to a specific version and includes the SHA-256 hash which are verified every time adrctl is built. You can inspect every aspect of adrctl, from source to build to release. Everything is open to the public.

My Bootstrap tool heavily influenced adrctl. I was pleased with the engineering processes and how smoothly everything grew. If I had to pick a single word for it, that word would be boring. It was boring in all the right ways. Things worked smoothly, processes and decisions were clearly documented, principled reasoning was used, and actions were resistant to tampering.

Other than the build and release improvements, the other major change was how templates were used. The template syntax from adr-tools was retained, but also expanded upon. Everything that adr-tools allowed is also allowed in adrctl. Templates were even used for filenames. That is, adrctl allows you to use an ADR naming convention that works for you by supporting templates for filenames.

This flexibility comes from a new library I developed with this project in mind, mktext, which I will discuss in a coming blog post.

If you’re interested in learning more about Architecture Decision Records (ADRs), please watch out for my coming book, Getting Started with Architecture Decision Records (ADRs), part of the Fewer Incidents series.