Skip to content

Commit c3c8f62

Browse files
febus982febus982
authored
MADR3 support (#2)
* Rename nygard adr example directory * Implement MADR3 parser * Rewrite Nygard parser * Use last status for Nygard format * Fix black config * Make adr_style mandatory * Update documentation --------- Signed-off-by: Federico Busetti <[email protected]>
1 parent 611e9f1 commit c3c8f62

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+934
-177
lines changed

‎.adr-dir‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
docs/adr
1+
docs/adr_nygard_example

‎README.md‎

Lines changed: 42 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,10 @@ This is a macro plugin to generates summaries from a list of a ADR documents in
1717

1818
Examples and documentation can be found [here](https://febus982.github.io/mkdocs-macros-adr-summary)
1919

20+
The package should be stable enough for daily use. I'll release 1.0.0, and switch to semantic version,
21+
as soon as support for MADR version 2 has been implemented. Until that breaking changes can be introduced
22+
and will be documented in the GitHub release description.
23+
2024
## Quick start
2125

2226
Enable the plugin in `mkdocs.yml`
@@ -31,20 +35,18 @@ Create a markdown page in your mkdocs website and use the `adr_summary` macro pr
3135
the path containing your ADR files relative to the `mkdocs.yml` file.
3236

3337
```markdown
34-
# Summary
35-
36-
{{ adr_summary(adr_path="docs/adr") }}
38+
{{ adr_summary(adr_path="docs/adr", adr_style="nygard") }}
3739
```
3840

41+
`adr_style` can be `nygard` or `MADR3`
42+
3943
## More customization
4044

4145
The page output is generated using a jinja template, but you can provide a custom one. The file path
4246
must still be relative to the `mkdocs.yml` file.
4347

4448
```markdown
45-
# Summary
46-
47-
{{ adr_summary(adr_path="docs/adr", template_file="other.jinja") }}
49+
{{ adr_summary(adr_path="docs/adr", adr_style="MADR3", template_file="other.jinja") }}
4850
```
4951

5052
The default template is:
@@ -65,23 +67,50 @@ The default template is:
6567
{% endfor %}
6668
```
6769

68-
The `document` variable in the jinja template is a Sequence of:
70+
The `documents` variable in the jinja template is a Sequence of `ADRDocument` models:
6971

7072
```python
7173
@dataclass
7274
class ADRDocument:
7375
file_path: str
74-
title: str
75-
date: Optional[date]
76-
statuses: Optional[Sequence[str]]
76+
title: Optional[str] = None
77+
date: Optional[date] = None
78+
stasdetus: Optional[str] = None
79+
statuses: Sequence[str] = tuple()
80+
deciders: Optional[str] = None
81+
consulted: Optional[str] = None
82+
informed: Optional[str] = None
7783
```
7884

85+
There are some differences in what metadata is available when using different formats:
86+
87+
| | Nygard | MADR3 | MADR2 |
88+
|-----------|--------|-------|-------|
89+
| file_path | ✅︎ | ✅︎ | ✅︎ |
90+
| title | ✅︎ | ✅︎ | ✅︎ |
91+
| date | ✅︎ | ✅︎ | TODO |
92+
| status | ⚠ | ✅︎ | TODO |
93+
| statuses | ✅︎ | ⚠ | TODO |
94+
| deciders | ❌ | ✅︎ | TODO |
95+
| consulted | ❌ | ✅︎ | TODO |
96+
| informed | ❌ | ✅︎ | TODO |
97+
98+
* **Nygard format**
99+
* `status` is the last item `statuses`. (I don't believe we should use multiple
100+
statuses, however `adr-tools` allows it)
101+
* `deciders`, `consulted` and `informed` are not supported by the format
102+
* **MADR3**
103+
* I wasn't able to find an automated tool supporting superseding documents.
104+
By looking at the template it looks like there's a single status.
105+
`statuses` will return a list with a single status.
106+
79107
## Supported ADR formats
80108

81-
The only supported ADR format currently is the `nygard` format, it is recommended to
82-
use [adr-tools](https://github.com/npryce/adr-tools) to manage the directory.
109+
The supported ADR formats are:
110+
* `nygard` format, it is recommended to use [adr-tools](https://github.com/npryce/adr-tools) to manage the directory
111+
* `MADR` [version 3](https://github.com/adr/madr/blob/3.0.0/template/adr-template.md)
83112

84-
Support for [MADR](https://adr.github.io/madr/) versions 2 and 3 will be added with future iterations.
113+
Support for [MADR](https://adr.github.io/madr/) version 2 will be added in a future version.
85114

86115
## Commands for development
87116

‎docs/.pages‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
nav:
22
- Home: index.md
3-
- ADR (Nygard format): adr
3+
- ADR Example (Nygard format): adr_nygard_example
4+
- ADR Example (MADR3 format): adr_madr3_example

‎docs/adr/summary.md‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

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

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Use Markdown Any Decision Records
2+
3+
## Context and Problem Statement
4+
5+
We want to record any decisions made in this project independent whether decisions concern the architecture ("architectural decision record"), the code, or other fields.
6+
Which format and structure should these records follow?
7+
8+
## Considered Options
9+
10+
* [MADR](https://adr.github.io/madr/) 2.1.2 – The Markdown Any Decision Records
11+
* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
12+
* Other templates listed at <https://schubmat.github.io/DecisionCapture>
13+
* Formless – No conventions for file format and structure
14+
15+
## Decision Outcome
16+
17+
Chosen option: "MADR 2.1.2", because
18+
19+
* Implicit assumptions should be made explicit.
20+
Design documentation is important to enable people understanding the decisions later on.
21+
See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
22+
* The MADR format is lean and fits our development style.
23+
* The MADR structure is comprehensible and facilitates usage & maintenance.
24+
* The MADR project is vivid.
25+
* Version 2.1.2 is the latest one available when starting to document ADRs.

‎docs/adr_madr2_example/template.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# [short title of solved problem and solution] source: https://github.com/adr/madr/tree/2.1.2/template
2+
3+
* Status: [proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)] <!-- optional -->
4+
* Deciders: [list everyone involved in the decision] <!-- optional -->
5+
* Date: [YYYY-MM-DD when the decision was last updated] <!-- optional -->
6+
7+
Technical Story: [description | ticket/issue URL] <!-- optional -->
8+
9+
## Context and Problem Statement
10+
11+
[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.]
12+
13+
## Decision Drivers <!-- optional -->
14+
15+
* [driver 1, e.g., a force, facing concern, …]
16+
* [driver 2, e.g., a force, facing concern, …]
17+
* … <!-- numbers of drivers can vary -->
18+
19+
## Considered Options
20+
21+
* [option 1]
22+
* [option 2]
23+
* [option 3]
24+
* … <!-- numbers of options can vary -->
25+
26+
## Decision Outcome
27+
28+
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)].
29+
30+
### Positive Consequences <!-- optional -->
31+
32+
* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]
33+
* …
34+
35+
### Negative Consequences <!-- optional -->
36+
37+
* [e.g., compromising quality attribute, follow-up decisions required, …]
38+
* …
39+
40+
## Pros and Cons of the Options <!-- optional -->
41+
42+
### [option 1]
43+
44+
[example | description | pointer to more information | …] <!-- optional -->
45+
46+
* Good, because [argument a]
47+
* Good, because [argument b]
48+
* Bad, because [argument c]
49+
* … <!-- numbers of pros and cons can vary -->
50+
51+
### [option 2]
52+
53+
[example | description | pointer to more information | …] <!-- optional -->
54+
55+
* Good, because [argument a]
56+
* Good, because [argument b]
57+
* Bad, because [argument c]
58+
* … <!-- numbers of pros and cons can vary -->
59+
60+
### [option 3]
61+
62+
[example | description | pointer to more information | …] <!-- optional -->
63+
64+
* Good, because [argument a]
65+
* Good, because [argument b]
66+
* Bad, because [argument c]
67+
* … <!-- numbers of pros and cons can vary -->
68+
69+
## Links <!-- optional -->
70+
71+
* [Link type] [Link to ADR] <!-- example: Refined by [ADR-0005](0005-example.md) -->
72+
* … <!-- numbers of links can vary -->

‎docs/adr_madr3_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/.pages renamed to docs/adr_madr3_example/.pages

File renamed without changes.

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

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

‎docs/adr_madr3_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/3.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+
deciders: {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.}

0 commit comments

Comments
 (0)