Skip to content

Commit

Permalink
Introduce ADRs (#203)
Browse files Browse the repository at this point in the history
It's a simple and effective way to write quick decision documents
  • Loading branch information
eikek authored Sep 13, 2024
1 parent be9e24f commit dc48c5a
Showing 1 changed file with 35 additions and 0 deletions.
35 changes: 35 additions & 0 deletions docs/adr/0000-use-markdown-architectural-decision-records.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Use Markdown Architectural Decision Records

## Context and Problem Statement

We want to record architectural decisions made in this project
independent whether decisions concern the architecture ("architectural
decision record"), the code, or other fields. Which format and
structure should these records follow?

## Considered Options

* [MADR](https://adr.github.io/madr/) 4.0.0 – The Markdown
Architectural Decision Records
* [Michael Nygard's
template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions)
– The first incarnation of the term "ADR"
* [Sustainable Architectural
Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions)
– The Y-Statements
* Other templates listed at
<https://github.com/joelparkerhenderson/architecture_decision_record>
* Formless – No conventions for file format and structure

## Decision Outcome

Chosen option: "MADR 4.0.0", because

* Implicit assumptions should be made explicit. Design documentation
is important to enable people understanding the decisions later on.
See also ["A rational design process: How and why to fake
it"](https://doi.org/10.1109/TSE.1986.6312940).
* MADR allows for structured capturing of any decision.
* The MADR format is lean and fits our development style.
* The MADR structure is comprehensible and facilitates usage &
maintenance.

0 comments on commit dc48c5a

Please sign in to comment.