Markdown Any Decision Records part of ADR

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

MADR is a lean template to capture any decisions in a structured way. The template originated from capturing architectural decisions and developed to a template allowing to capture any decisions taken.

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 Any Decision Records.

Before MADR 3.0.0, “MADR” stood for Markdown and Architectural Decision Records. Since MADR 3.0.0, “Architectural” was replaced by “Any”.

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/main/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/main/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 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 sub directories and put the ADRs into these folders.

An examplary 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 sub directory/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-0005](0005-example.md)}
# date: {YYYY-MM-DD when the decision was last updated}
# deciders: {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 of solved problem and 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. -->
## Validation

{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test}

<!-- 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 this decision when and how the decision should be realized and if/when it should be re-visited and/or
 how the decision is validated.
 Links to other decisions and resources might here appear as well.}

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