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:
a brief title of the decision
a status of the decision (proposed / accepted / pending / rejected)
a summary of the decision, and context about why we are making it.
The decision itself (ex: use certain library)
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
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 looks like
- You can also generate a graph of your ADRs
adr generate graph
This will generate a graph of your decisions