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]>

.adr-dir

@@ -1 +1 @@
-docs/adr
+docs/adr_nygard_example

README.md

@@ -17,6 +17,10 @@ This is a macro plugin to generates summaries from a list of a ADR documents in
 
 Examples and documentation can be found [here](https://febus982.github.io/mkdocs-macros-adr-summary)
 
+The package should be stable enough for daily use. I'll release 1.0.0, and switch to semantic version,
+as soon as support for MADR version 2 has been implemented. Until that breaking changes can be introduced
+and will be documented in the GitHub release description.
+
 ## Quick start
 
 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
 the path containing your ADR files relative to the `mkdocs.yml` file.
 
 ```markdown
-# Summary
-
-{{ adr_summary(adr_path="docs/adr") }}
+{{ adr_summary(adr_path="docs/adr", adr_style="nygard") }}
 ```
 
+`adr_style` can be `nygard` or `MADR3`
+
 ## More customization
 
 The page output is generated using a jinja template, but you can provide a custom one. The file path
 must still be relative to the `mkdocs.yml` file.
 
 ```markdown
-# Summary
-
-{{ adr_summary(adr_path="docs/adr", template_file="other.jinja") }}
+{{ adr_summary(adr_path="docs/adr", adr_style="MADR3", template_file="other.jinja") }}
 ```
 
 The default template is:
@@ -65,23 +67,50 @@ The default template is:
 {% endfor %}
 ```
 
-The `document` variable in the jinja template is a Sequence of:
+The `documents` variable in the jinja template is a Sequence of `ADRDocument` models:
 
 ```python
 @dataclass
 class ADRDocument:
     file_path: str
-    title: str
-    date: Optional[date]
-    statuses: Optional[Sequence[str]]
+    title: Optional[str] = None
+    date: Optional[date] = None
+    stasdetus: Optional[str] = None
+    statuses: Sequence[str] = tuple()
+    deciders: Optional[str] = None
+    consulted: Optional[str] = None
+    informed: Optional[str] = None
 ```
 
+There are some differences in what metadata is available when using different formats:
+
+|           | Nygard | MADR3 | MADR2 |
+|-----------|--------|-------|-------|
+| file_path | ✅︎     | ✅︎    | ✅︎    |
+| title     | ✅︎     | ✅︎    | ✅︎    |
+| date      | ✅︎     | ✅︎    | TODO  |
+| status    | ⚠      | ✅︎    | TODO  |
+| statuses  | ✅︎     | ⚠     | TODO  |
+| deciders  | ❌      | ✅︎    | TODO  |
+| consulted | ❌      | ✅︎    | TODO  |
+| informed  | ❌      | ✅︎    | TODO  |
+
+* **Nygard format**
+  * `status` is the last item `statuses`. (I don't believe we should use multiple
+    statuses, however `adr-tools` allows it)
+  * `deciders`, `consulted` and `informed` are not supported by the format
+* **MADR3**
+  * I wasn't able to find an automated tool supporting superseding documents.
+    By looking at the template it looks like there's a single status.
+    `statuses` will return a list with a single status.
+
 ## Supported ADR formats
 
-The only supported ADR format currently is the `nygard` format, it is recommended to
-use [adr-tools](https://github.com/npryce/adr-tools) to manage the directory.
+The supported ADR formats are:
+* `nygard` format, it is recommended to use [adr-tools](https://github.com/npryce/adr-tools) to manage the directory
+* `MADR` [version 3](https://github.com/adr/madr/blob/3.0.0/template/adr-template.md)
 
-Support for [MADR](https://adr.github.io/madr/) versions 2 and 3 will be added with future iterations.
+Support for [MADR](https://adr.github.io/madr/) version 2 will be added in a future version.
 
 ## Commands for development
 

docs/.pages

@@ -1,3 +1,4 @@
 nav:
   - Home: index.md
-  - ADR (Nygard format): adr
+  - ADR Example (Nygard format): adr_nygard_example
+  - ADR Example (MADR3 format): adr_madr3_example

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

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

docs/adr_madr2_example/template.md

@@ -0,0 +1,72 @@
+# [short title of solved problem and solution] source: https://github.com/adr/madr/tree/2.1.2/template
+
+* Status: [proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)] <!-- optional -->
+* Deciders: [list everyone involved in the decision] <!-- optional -->
+* Date: [YYYY-MM-DD when the decision was last updated] <!-- optional -->
+
+Technical Story: [description | ticket/issue URL] <!-- optional -->
+
+## Context and Problem Statement
+
+[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.]
+
+## Decision Drivers <!-- optional -->
+
+* [driver 1, e.g., a force, facing concern, …]
+* [driver 2, e.g., a force, facing concern, …]
+* … <!-- numbers of drivers can vary -->
+
+## 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]
+
+[example | description | pointer to more information | …] <!-- optional -->
+
+* Good, because [argument a]
+* Good, because [argument b]
+* Bad, because [argument c]
+* … <!-- numbers of pros and cons can vary -->
+
+### [option 2]
+
+[example | description | pointer to more information | …] <!-- optional -->
+
+* Good, because [argument a]
+* Good, because [argument b]
+* Bad, because [argument c]
+* … <!-- numbers of pros and cons can vary -->
+
+### [option 3]
+
+[example | description | pointer to more information | …] <!-- optional -->
+
+* Good, because [argument a]
+* Good, because [argument b]
+* Bad, because [argument c]
+* … <!-- numbers of pros and cons can vary -->
+
+## Links <!-- optional -->
+
+* [Link type] [Link to ADR] <!-- example: Refined by [ADR-0005](0005-example.md) -->
+* … <!-- numbers of links can vary -->

docs/adr_madr3_example/.markdownlint

@@ -0,0 +1,20 @@
+# source: https://github.com/adr/madr/blob/3.0.0/template/.markdownlint.yml
+default: true
+
+# Allow arbitrary line length
+#
+# Reason: We apply the one-sentence-per-line rule. A sentence may get longer than 80 characters, especially if links are contained.
+#
+# Details: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md013---line-length
+MD013: false
+
+# Allow duplicate headings
+#
+# Reasons:
+#
+# - The chosen option is considerably often used as title of the ADR (e.g., ADR-0015). Thus, that title repeats.
+# - We use "Examples" multiple times (e.g., ADR-0010).
+# - Markdown lint should support the user and not annoy them.
+#
+# Details: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md024---multiple-headings-with-the-same-content
+MD024: false

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

@@ -0,0 +1,36 @@
+---
+# source: https://github.com/adr/madr/blob/3.0.0/template/adr-template.md
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+date: 2024-01-24
+# 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}
+---
+# Use Markdown Any Decision Records
+
+## Context and Problem Statement
+
+We want to record any decisions made in this project independent whether decisions concern the architecture ("architectural decision record"), the code, or other fields.
+Which format and structure should these records follow?
+
+## Considered Options
+
+* [MADR](https://adr.github.io/madr/) 3.0.0 – The Markdown Any Decision Records
+* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
+* Other templates listed at <https://schubmat.github.io/DecisionCapture>
+* Formless – No conventions for file format and structure
+
+## Decision Outcome
+
+Chosen option: "MADR 3.0.0", because
+
+* Implicit assumptions should be made explicit.
+  Design documentation is important to enable people understanding the decisions later on.
+  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
+* MADR allows for structured capturing of any decision.
+* The MADR format is lean and fits our development style.
+* The MADR structure is comprehensible and facilitates usage & maintenance.
+* The MADR project is vivid.

docs/adr_madr3_example/adr-template.md

@@ -0,0 +1,80 @@
+---
+# source: https://github.com/adr/madr/blob/3.0.0/template/adr-template.md
+# 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}
+---
+# {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.}

docs/adr_madr3_example/summary.md

@@ -0,0 +1,3 @@
+# Summary
+
+{{ adr_summary(adr_path="docs/adr_madr3_example", adr_style="MADR3") }}

docs/adr_nygard_example/.pages

@@ -0,0 +1,5 @@
+order: desc
+
+nav:
+  - summary.md
+  - ...

docs/adr_nygard_example/summary.md

@@ -0,0 +1,3 @@
+# Summary
+
+{{ adr_summary(adr_path="docs/adr_nygard_example", adr_style="nygard") }}