Skip to content

Commit b545d4e

Browse files
noirbizarrenoirbizarre
authored
feat(madr4): add support for MADR 4.0 (#32)
1 parent 8efa577 commit b545d4e

18 files changed

+460
-14
lines changed

‎README.md‎

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ the path containing your ADR files relative to the `mkdocs.yml` file.
4444
{{ adr_summary(adr_path="docs/adr", adr_style="nygard") }}
4545
```
4646

47-
`adr_style` can be `nygard` or `MADR3`
47+
`adr_style` can be `nygard`, `MADR2`, `MADR3`, or `MADR4`
4848

4949
## More customization
5050

@@ -82,30 +82,32 @@ class ADRDocument:
8282

8383
There are some differences in what metadata is available when using different formats:
8484

85-
| | Nygard | MADR3 | MADR2 |
86-
|-----------|--------|-------|-------|
87-
| file_path | ✅︎ | ✅︎ | ✅︎ |
88-
| title | ✅︎ | ✅︎ | ✅︎ |
89-
| date | ✅︎ | ✅︎ | ✅︎ |
90-
| status | ⚠ | ✅︎ | ✅︎ |
91-
| statuses | ✅︎ | ⚠ | ⚠ |
92-
| deciders | ❌ | ✅︎ | ✅︎ |
93-
| consulted | ❌ | ✅︎ | ❌ |
94-
| informed | ❌ | ✅︎ | ❌ |
85+
| | Nygard | MADR4 | MADR3 | MADR2 |
86+
|-----------|--------|-------|-------|-------|
87+
| file_path | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
88+
| title | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
89+
| date | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
90+
| status | ⚠ | ✅︎ | ✅︎ | ✅︎ |
91+
| statuses | ✅︎ | ⚠ | ⚠ | ⚠ |
92+
| deciders | ❌ | ✅︎ | ✅︎ | ✅︎ |
93+
| consulted | ❌ | ✅︎ | ✅︎ | ❌ |
94+
| informed | ❌ | ✅︎ | ✅︎ | ❌ |
9595

9696
* **Nygard format**
9797
* `status` is the last item `statuses`. (I don't believe we should use multiple
9898
statuses, however `adr-tools` allows it)
9999
* `deciders`, `consulted` and `informed` are not supported by the format
100-
* **MADR2** and **MADR3**
100+
* **MADR2**, **MADR3**, and **MADR4**
101101
* I wasn't able to find an automated tool supporting superseding documents.
102102
By looking at the template it looks like there's a single status.
103103
`statuses` will return a list with a single status.
104+
* MADR4 uses `decision-makers` instead of `deciders` in the YAML frontmatter, but the parser maps it to the `deciders` field in the document model
104105

105106
## Supported ADR formats
106107

107108
The supported ADR formats are:
108109
* `nygard` format, it is recommended to use [adr-tools](https://github.com/npryce/adr-tools) to manage the directory
110+
* `MADR` [version 4](https://github.com/adr/madr/blob/4.0.0/template/adr-template.md)
109111
* `MADR` [version 3](https://github.com/adr/madr/blob/3.0.0/template/adr-template.md)
110112
* `MADR` [version 2](https://github.com/adr/madr/blob/2.1.2/template/template.md)
111113

‎docs/adr_madr4_example/.markdownlint‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# source: https://github.com/adr/madr/blob/3.0.0/template/.markdownlint.yml
2+
default: true
3+
4+
# Allow arbitrary line length
5+
#
6+
# Reason: We apply the one-sentence-per-line rule. A sentence may get longer than 80 characters, especially if links are contained.
7+
#
8+
# Details: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md013---line-length
9+
MD013: false
10+
11+
# Allow duplicate headings
12+
#
13+
# Reasons:
14+
#
15+
# - The chosen option is considerably often used as title of the ADR (e.g., ADR-0015). Thus, that title repeats.
16+
# - We use "Examples" multiple times (e.g., ADR-0010).
17+
# - Markdown lint should support the user and not annoy them.
18+
#
19+
# Details: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md024---multiple-headings-with-the-same-content
20+
MD024: false

‎docs/adr_madr4_example/.pages‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
nav:
2+
- Summary: summary.md
3+
- ... | regex=^\d{4}-
4+

‎docs/adr_madr4_example/0001-record-architecture-decisions.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
# source: https://github.com/adr/madr/blob/4.0.0/template/adr-template.md
3+
# These are optional elements. Feel free to remove any of them.
4+
status: superseded by [ADR-0002](0002-change-mind.md)
5+
date: 2024-01-24
6+
decision-makers: Nick Fury, Tony Stark
7+
# status: {proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)}
8+
# date: {YYYY-MM-DD when the decision was last updated}
9+
# decision-makers: {list everyone involved in the decision}
10+
# consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
11+
# informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
12+
---
13+
# Use Markdown Any Decision Records
14+
15+
## Context and Problem Statement
16+
17+
We want to record any decisions made in this project independent whether decisions concern the architecture ("architectural decision record"), the code, or other fields.
18+
Which format and structure should these records follow?
19+
20+
## Considered Options
21+
22+
* [MADR](https://adr.github.io/madr/) 4.0.0 – The Markdown Any Decision Records
23+
* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
24+
* Other templates listed at <https://schubmat.github.io/DecisionCapture>
25+
* Formless – No conventions for file format and structure
26+
27+
## Decision Outcome
28+
29+
Chosen option: "MADR 4.0.0", because
30+
31+
* Implicit assumptions should be made explicit.
32+
Design documentation is important to enable people understanding the decisions later on.
33+
See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
34+
* MADR allows for structured capturing of any decision.
35+
* The MADR format is lean and fits our development style.
36+
* The MADR structure is comprehensible and facilitates usage & maintenance.
37+
* The MADR project is vivid.

‎docs/adr_madr4_example/0002-change-mind.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
# source: https://github.com/adr/madr/blob/4.0.0/template/adr-template.md
3+
# These are optional elements. Feel free to remove any of them.
4+
status: accepted
5+
date: 2024-01-25
6+
decision-makers: Nick Fury, Tony Stark
7+
---
8+
# Changed my mind about ADR format
9+
10+
## Context and Problem Statement
11+
12+
For some reason we don't like MADR anymore.

‎docs/adr_madr4_example/adr-template.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
# source: https://github.com/adr/madr/blob/4.0.0/template/adr-template.md
3+
# These are optional elements. Feel free to remove any of them.
4+
status: {proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)}
5+
date: {YYYY-MM-DD when the decision was last updated}
6+
decision-makers: {list everyone involved in the decision}
7+
consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
8+
informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
9+
---
10+
# {short title of solved problem and solution}
11+
12+
## Context and Problem Statement
13+
14+
{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story.
15+
You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}
16+
17+
<!-- This is an optional element. Feel free to remove. -->
18+
## Decision Drivers
19+
20+
* {decision driver 1, e.g., a force, facing concern, …}
21+
* {decision driver 2, e.g., a force, facing concern, …}
22+
* … <!-- numbers of drivers can vary -->
23+
24+
## Considered Options
25+
26+
* {title of option 1}
27+
* {title of option 2}
28+
* {title of option 3}
29+
* … <!-- numbers of options can vary -->
30+
31+
## Decision Outcome
32+
33+
Chosen option: "{title of option 1}", because
34+
{justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
35+
36+
<!-- This is an optional element. Feel free to remove. -->
37+
### Consequences
38+
39+
* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
40+
* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
41+
* … <!-- numbers of consequences can vary -->
42+
43+
<!-- This is an optional element. Feel free to remove. -->
44+
## Validation
45+
46+
{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test}
47+
48+
<!-- This is an optional element. Feel free to remove. -->
49+
## Pros and Cons of the Options
50+
51+
### {title of option 1}
52+
53+
<!-- This is an optional element. Feel free to remove. -->
54+
{example | description | pointer to more information | …}
55+
56+
* Good, because {argument a}
57+
* Good, because {argument b}
58+
<!-- use "neutral" if the given argument weights neither for good nor bad -->
59+
* Neutral, because {argument c}
60+
* Bad, because {argument d}
61+
* … <!-- numbers of pros and cons can vary -->
62+
63+
### {title of other option}
64+
65+
{example | description | pointer to more information | …}
66+
67+
* Good, because {argument a}
68+
* Good, because {argument b}
69+
* Neutral, because {argument c}
70+
* Bad, because {argument d}
71+
* …
72+
73+
<!-- This is an optional element. Feel free to remove. -->
74+
## More Information
75+
76+
{You might want to provide additional evidence/confidence for the decision outcome here and/or
77+
document the team agreement on the decision and/or
78+
define when this decision when and how the decision should be realized and if/when it should be re-visited and/or
79+
how the decision is validated.
80+
Links to other decisions and resources might here appear as well.}

‎docs/adr_madr4_example/summary.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# ADR Summary
2+
3+
{{ adr_summary(adr_path="docs/adr_madr4_example", adr_style="MADR4") }}

‎mkdocs_macros_adr_summary/factory.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,11 @@
2121
from typing import Dict, Type
2222

2323
from .interfaces import ADRParser, TYPE_ADRStyle
24-
from .parser import MADR2Parser, MADR3Parser, NygardParser
24+
from .parser import MADR2Parser, MADR3Parser, MADR4Parser, NygardParser
2525

2626
parser_registry: Dict[TYPE_ADRStyle, Type[ADRParser]] = {
2727
"nygard": NygardParser,
28+
"MADR4": MADR4Parser,
2829
"MADR3": MADR3Parser,
2930
"MADR2": MADR2Parser,
3031
}

‎mkdocs_macros_adr_summary/interfaces.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
from pathlib import Path
2525
from typing import Literal, Optional, Sequence
2626

27-
TYPE_ADRStyle = Literal["MADR2", "MADR3", "nygard"]
27+
TYPE_ADRStyle = Literal["MADR2", "MADR3", "MADR4", "nygard"]
2828

2929

3030
@dataclass

‎mkdocs_macros_adr_summary/parser/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,4 +29,5 @@
2929
#
3030
from .madr2 import MADR2Parser
3131
from .madr3 import MADR3Parser
32+
from .madr4 import MADR4Parser
3233
from .nygard import NygardParser

0 commit comments

Comments
 (0)