I have been looking for a way to introduce clarity over the changes made to the codebase.

Until I stumbled upon architecture decision record (adr)

What is an ADR?

An architecture decision record (ADR) is a document that captures an important architectural decision made along with its context and consequences.

There are different templates of adr you can adopt, but a typical adr will contain:

Title

a brief title of the decision

Status

a status of the decision (proposed / accepted / pending / rejected)

Context

a summary of the decision, and context about why we are making it.

Decision

The decision itself (ex: use certain library)

Consequences

cons and pros from that decision

Why do we use ADRs?

• Because not all decisions will be made at once, nor will all of them be done when the project begins.

• To track the motivation behind certain decisions during the life of a project.

• Because without understanding the rationale of consequences behind decision people have two choices:

  • Blindly accept the decision without understanding.
  • Blindly change the decision because of lack of understanding.

How to create ADRs?

ADRs are text files at the end, you can create them manually in your project, or use a cli too like adr-tools to do that

• Installation

brew install adr-tools
adr init

• Add ADRs to your project

cd Project/
adr init

• Create your first adr:

adr new use mockery for unit tests

Your directory structure will look like this

• You can also generate a graph of your ADRs

adr generate graph

This will generate a graph of your decisions