Architectural Design Decisions (ADR)

The following is Andy Dote's summary of Architectural Design Decisions:

Architecture Design Records are there to solve the main question people repeatedly ask when they view a new codebase or look at an older part of their current codebase:

Why on earth was it done like this?!

Generally speaking, architectural decisions have been made in good faith at the time, but as time marches on, things change, and the reasoning gets lost. The reasoning might be discoverable through the commit history, or some comments in a type somewhere, and every once in a while, people remember the Wiki exists, and hope that someone else remembered and put some docs there. They didn’t by the way.

Architecture Design Records are aiming to solve all of this, with three straightforward attributes: Easy to Write, Easy to Read, and Easy to Find.

To find out more about ADR, see the References section below.

Setup

Before getting started make sure the following utilities are present:

• adr-tools
• adr-log

Usage

(1) Initialize your repository to use ADR

# cd into your repo root

# if not done already, then initialize the ADR document directory
adr init

(2) Create a new decision

# create a new design decision, e.g., `adr new "Title of your design decision"`
adr new "Do whiteboard wednesday talks" 

# fill in the "Context", "Decision", and "Consequences" of the new doc
vim doc/adr/0002-do-whiteboard-wednesday-talks.md

(3) Add a 'table of contents' for your design decisions to your root-level README

The following is the raw markdown showing the required adrlog and adrlogstop tags (ignore any [ADR-xxxx] entries):

<!-- adrlog -->

* [ADR-0001](doc/adr/0001-record-architecture-decisions.md) - Record architecture decisions
* [ADR-0002](doc/adr/0002-dry-up-duplicated-code-in-github-actions.md) - Dry up duplicated code in github actions

<!-- adrlogstop -->

The above list of sample ADR's was generated by the next step, which populates a list of all ADR's between the adrlog and adrlogstop tags.

(4) Update the decision 'table of contents'

After adding new design decision records, then remember to update the table of contents in the root-level README:

# update the `README.md` table of contents to include the newest design decision
adr-log -i README.md -d doc

References

The command-line tools

• npryce/adr-tools: Command-line tools for working with Architecture Decision Records
• adr/adr-log: Generate an architectural decision record log (adr-log) out of architectural decision records (ADRs)

Background information

• Architecture Decision Records (ADR) as a LOG that answers "WHY?" - CodeOpinion
• Documenting Architecture Decisions
• Architecture Decision Records (ADR) as a LOG that answers "WHY?" - YouTube
• Architecture Decision Records | Andy Dote
• Communicating and documenting architectural decisions - David Ayers
• Thoughworks Technology Radar: Lightweight Architecture Decision Records