adr-tools
Many teams discuss and maintain ADRs using tools like Confluence and Wiki. We all know perfectly well that this is a “write once, read never”
approach.
On my team I decided right away to keep ADRs inside the project’s
end-to-end technical documentation using adr-tools. That gives us:
- an unbroken link between code, docs, and
ADRs; - a single process for shipping changes;
- accessibility, openness, and a built-in notification flow for changes.
Creating, reviewing, and superseding ADRs goes through the same Merge
Request flow as code. While reviewing an MR, it’s easy to suggest edits or attach patches that can be applied right away.
The adr-tools version is pinned at the root of the docs repository in asdf’s .tool-versions file. That guarantees my coworkers use a strictly
defined version of the tool:
cat .tool-versions
adr-tools 3.0.0
adr-tools has a very simple command-line interface:
adr init [path]— initializes theADRdirectory. I recommend running this command at the root of the docs repository and pointing it at a dedicated folder forADRs. The command creates an.adr-dirfile in the current directory pointing to the folder you just created. That makes it much easier to run theadrcommand straight from the repository root afterwards.adr new Use linters for code— creates a new.mdentry from the template proposed by Michael Nygard, using the title passed as an argument.adr new -s NUMBER Stop using linters for code— creates a newADRthat supersedes the older one whose number is passed as an argument.
In practice, adr-tools is probably the only reliable and portable
tool for maintaining ADRs.
The template proposed by Michael Nygard is the best, if not the only one,
among the alternatives.