Architecture Decision Record

Documents to keep track of Software Architecture decisions and their evolution. ADR's are
related to (and may succeed) RFCs, which are widely used by the IETF.

Rationale
The body in charge of Software Architecture must not only decide on architectural concerns,
but also communicate and enforce their decisions. The means of propagating those
deliberations, their context and especially the inevitable changes in understanding as the
project evolves is often inefficient (such as e-mail driven architecture, where supposedly
interested parties are notified of architectural decisions through email). ADRs offer a structured
approach for recording architecture decisions, explaining why they were taken (as opposed to
diagrams, because Software Architecture > Diagrams miss the point), who they affect and
how they are impacted.

ADRs require significant effort and discussion, making them unsuitable for minor and low-
impactful matters such as "service X will favour composition over inheritance".

Structure
Title
Brief description of the decision.

Status
Possible statuses are:

Proposed: under analysis. May be changed many times

Accepted: the proposal has been accepetd by the comittee, and will be implemented
Superseded: when the ADR has been overwritten by a newer one. This helps teams keep
track of the evolution in understanding, as well as avoiding mistakes of the pass (or
reassesing what was already discarded)

Context
What sparked the debate? Why must this decision be made? What was assessed? What does
this solve?

What other options were considered, and why were they discarded? Will they ever be
reconsidered?

Who is affected? Which components?

Decision
The decision itself and the rationale behind it.

Consequences
Now that the decision was made, what happens?

Compliance
Who will implement this decision? When? How will it be validated?

Notes
Metadata, authors or any other relevant footnotes.