"Markdown Architectural Decision Records" (MADR)
[ˈmæɾɚ]– architectural decisions that matter[ˈmæɾɚ].
An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. This might, for instance, be a technology choice (e.g., Java vs. JavaScript), a choice of the IDE (e.g., IntelliJ vs. Eclipse IDE), a choice between a library (e.g., SLF4J vs java.util.logging), or a decision on features (e.g., infinite undo vs. limited undo). Do not take the term "architecture" too serious or interpret it too strong. As the examples illustrate, any decision might have impact on the architecture somehow are architectural decisions.
It should be as easy as possible to a) write down the decisions and b) to version the decisions.
This repository offers a solution to record architectural decisions. It provides provides an initial directory structure and files to document Architectural Decisions using Markdown and Architectural Decision Records.
The decisions are placed in the folder docs/adr to
- Enable GitHub pages to render it using in the web. See https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/ for more information.
- Separate the architectural decisions from other documentation.
The template reads as follows:
# [short title of solved problem and solution]
User Story: [ticket/issue-number] <!-- optional -->
[context and problem statement]
[decision drivers | forces | facing] <!-- optional -->
## Considered Options
* [option 1]
* [option 2]
* [option 3]
* ... <!-- numbers of options can vary -->
## Decision Outcome
Chosen option: [option 1], because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | ... | comes out best (see below)].
Positive Consequences: <!-- optional -->
- [e.g., improvement of quality attribute satisfaction, follow-up decisions required, ...]
- ...
Negative consequences: <!-- optional -->
- [e.g., compromising quality attribute, follow-up decisions required, ...]
- ...
## Pros and Cons of the Options <!-- optional -->
### [option 1]
* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]
* ... <!-- numbers of pros and cons can vary -->
### [option 2]
* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]
* ... <!-- numbers of pros and cons can vary -->
### [option 3]
* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]
* ... <!-- numbers of pros and cons can vary -->The template is available at template/template.md.
# Use Markdown Architectural Decision Records (MADR)
Should we record the architectural decisions made in this project?
And if we do, how to structure these recordings?
## Considered Options
* [MADR](https://github.com/adr/madr) - 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". Maintainable by [adr-tools](https://github.com/npryce/adr-tools).
* [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) - The Y-Statements
* [DecisionRecord](https://github.com/schubmat/DecisionCapture) - Agile records by [@schubmat](https://github.com/schubmat/)
* Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
* No records
## Decision Outcome
* Chosen option: MADR
* The MADR template is lean and fits our development style.The example is rendered at template/0000-use-markdown-architectural-decision-records.md
For the MADR project itself, all ADRs are exist at docs/adr/.
Create folder docs/adr in your project.
Copy all files in template from the MADR project to the folder docs/adr in your project.
For instance, using npm, this can be done using the following command:
$ npm install madr && mkdir -p docs/adr && cp node_modules/madr/template/* docs/adr/Manual approach:
- Copy
template.mdtoNNNN-title-with-dashes.md, whereNNNNindicates the next number in sequence. - Edit
NNNN-title-with-dashes.md. - Update
index.md, e.g., by executingadr-log -d .You can get adr-log from https://github.com/adr/adr-log.
We are working to enhance an adr tool (such as adr-j, adr-tools, or adr) to provide support for MADR.
The Y-Statements (presented as "Sustainable Architectural Design Decisions") are the most prominent alternative of this template. They are even shorter as their minimal form is just one sentence:
In the context of <use case/user story u>,
facing <concern c>
we decided for <option o>
and neglected <other options>,
to achieve <system qualities/desired consequences>,
accepting <downside d/undesired consequences>,
because <additional rationale>.
Both MADR and the Y-Statements can embedded in Java code using the e-adr library.
For more information on ADRs check http://adr.github.io.
License: CC0