Markdown Architectural Decision Records part of ADR

“Markdown Architectural Decision Records” (MADR) [ˈmæɾɚ] – decisions that matter [ˈmæɾɚ].

An Architectural Decision (AD) is a justified software design choice that addresses a functional or non-functional requirement of architectural significance. This decision is documented in an Architectural Decision Record (ADR), which details a single AD and its underlying rationale. To capture these records in a lean way, the Markdown Architectural Decision Records (MADRs) have been invented: MADR is a streamlined template for recording architectural significant decisions in a structured manner.

Contents

News

Overview

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 seriously or interpret it too strongly. As the examples illustrate, any decisions that might have an 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.

There are debates about what is an architecturally-significant decision and which decisions are not architecturally significant. Since we believe that any (important) decision should be captured in a structured way, we offer the MADR template to capture any decision.

This repository offers a solution to record any decisions. It provides files to document any decisions using Markdown and Architectural Decision Records.

Example 

# Use Plain JUnit5 for advanced test assertions

## Context and Problem Statement

How to write readable test assertions?
How to write readable test assertions for advanced tests?

## Considered Options

* Plain JUnit5
* Hamcrest
* AssertJ

## Decision Outcome

Chosen option: "Plain JUnit5", because it is a standard framework and the features of the other frameworks do not outweigh the drawbrack of adding a new dependency.

For more examples see examples. For the MADR project itself, all ADRs are rendered at decisions/. Their source can be found at https://github.com/adr/madr/tree/develop/docs/decisions. The latest release of the full template (with placeholders and some guidance how to use) can be found at the releases page. By clicking on the number at the tag symbol, you browse the repository at the state of the release. For the brave, the version under development is available at https://github.com/adr/madr/blob/develop/template/adr-template.md. There also is a CHANGELOG listing the changes between the last released version and the currently developed version.

Applying MADR to your project

Initialization

Create folder docs/decisions in your project. Copy all files in folder template from the MADR project to the folder docs/decisions in your project.

Using npm, this can be done using the following command:

npm install madr && mkdir -p docs/decisions && cp node_modules/madr/template/* docs/decisions/

Create a new ADR

Manual approach

  1. Copy docs/decisions/adr-template.md to docs/decisions/NNNN-title-with-dashes.md, where NNNN indicates the next number in sequence.
  2. Edit NNNN-title-with-dashes.md.

Note you can also use other patterns for the directory format. As a consequence, some existing tooling might not be applicable.

The filenames are following the pattern NNNN-title-with-dashes.md (ADR-0005), where

  • NNNN is a consecutive number and we assume that there won’t be more than 9,999 ADRs in one repository.
  • The title is stored using dashes and lowercase, because [adr-tools] also does that.
  • The suffix is .md, because it is a Markdown file.

Decisions are placed in the subfolder decisions/ to keep them close to the documentation but also separate the decisions from other documentation.

Automatic approach

There is currently no tooling supporting MADR 3.0.0.

Lint ADRs

ADRs are written using Markdown. Since Markdown allows many styles, formatting can be inconsistent. To notify about inconsistencies, markdownlint has been invented. There is an initial configuration for it at template/.markdownlint. You can use that configuration in a GitHub workflow. See .github/workflows/lint.yaml for an example.

Using MADR in large projects and product developments

Large projects may accumulate hundreds of decision records over time, and finding them might be hard. MADR does not enforce any repository or directory organization structure. Some proposals from the community are presented in the following.

Usage of categories

MADR logs may be categorized ADRs by defining subdirectories and put the ADRs into these folders.

An exemplary folder structure might follow the architectural structure of the system under construction:

.
`-- decisions
    |-- backend
    |   |-- 0001-use-quarkus.md
    `-- ui
        `-- 0001-use-vuejs.md

This approach makes all categories explicit because the subdirectory/folder names define the categories. As a consequence, numbers of ADRs are no longer unique throughout the repository, but locally within a category only. Ideally, the ADR categorization the same organizing principles as other artifacts such as the code; using architectural structure breakdown is just one option and functional decomposition would be an additional one. This comes down to a meta-decision to be made rather early on.

Note that alternatives to categorization via subfolders are discussed at ADR-0010.

Full template

The current development version renders as follows:

---
# Configuration for the Jekyll template "Just the Docs"
parent: Decisions
nav_order: 100
title: ADR Template

# These are optional elements. Feel free to remove any of them.
# status: "{proposed | rejected | accepted | deprecated | … | superseded by ADR-0123"
# date: {YYYY-MM-DD when the decision was last updated}
# decision-makers: {list everyone involved in the decision}
# consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
# informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
---
<!-- we need to disable MD025, because we use the different heading "ADR Template" in the homepage (see above) than it is foreseen in the template -->
<!-- markdownlint-disable-next-line MD025 -->
# {short title, representative of solved problem and found solution}

## Context and Problem Statement

{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}

<!-- This is an optional element. Feel free to remove. -->
## Decision Drivers

* {decision driver 1, e.g., a force, facing concern, …}
* {decision driver 2, e.g., a force, facing concern, …}
* … <!-- numbers of drivers can vary -->

## Considered Options

* {title of option 1}
* {title of option 2}
* {title of option 3}
* … <!-- numbers of options can vary -->

## Decision Outcome

Chosen option: "{title of option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.

<!-- This is an optional element. Feel free to remove. -->
### Consequences

* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
* … <!-- numbers of consequences can vary -->

<!-- This is an optional element. Feel free to remove. -->
### Confirmation

{Describe how the implementation of/compliance with the ADR can/will be confirmed. Are the design that was decided for and its implementation in line with the decision made? E.g., a design/code review or a test with a library such as ArchUnit can help validate this. Not that although we classify this element as optional, it is included in many ADRs.}

<!-- This is an optional element. Feel free to remove. -->
## Pros and Cons of the Options

### {title of option 1}

<!-- This is an optional element. Feel free to remove. -->
{example | description | pointer to more information | …}

* Good, because {argument a}
* Good, because {argument b}
<!-- use "neutral" if the given argument weights neither for good nor bad -->
* Neutral, because {argument c}
* Bad, because {argument d}
* … <!-- numbers of pros and cons can vary -->

### {title of other option}

{example | description | pointer to more information | …}

* Good, because {argument a}
* Good, because {argument b}
* Neutral, because {argument c}
* Bad, because {argument d}
* …

<!-- This is an optional element. Feel free to remove. -->
## More Information

{You might want to provide additional evidence/confidence for the decision outcome here and/or document the team agreement on the decision and/or define when/how this decision the decision should be realized and if/when it should be re-visited. Links to other decisions and resources might appear here as well.}

Older versions

Version Branch Homepage
1.x release/v1 README.md
2.x release/v2 README.md
3.x release/v3 index.md

The branch name conventions follow the git flow model.

License

This work is dual-licensed under MIT and CC0. You can choose between one of them if you use this work.

SPDX-License-Identifier: MIT OR CC0-1.0