| status | date | decision-makers | consulted | informed |
|---|---|---|---|---|
accepted |
2024-11-05 |
Joris MASSON |
Manuel VACELET, Thomas GERBET, Nicolas TERRAY |
Thomas GORKA, Thomas GERBET, Nicolas TERRAY, Clarck ROBINSON, Marie Ange GARNIER, Kevin TRAINI, Manuel VACELET, Clarisse DESCHAMPS |
Since the first ADR we wrote in 2021, we have been using the MADR template for Architectural Decision Records at version 2.1.2. We didn't document it at the time, but the template text matches exactly our copy. Since then, the MADR template has seen a number of revisions that could be interesting for us. Which format and folder structure should our ADRs follow ?
request #40439 Adopt MADR v4 template for ADRs
- Switch to MADR v4.0.0
- Status quo: Keep using MADR v2.1.2
Chosen option: "Switch to MADR v4.0.0", because it comes out best (see below).
- It brings interesting changes to the template, such as the "Confirmation" section to incite ADR writers to think about how/when a decision can be considered "done".
- It simplifies the template: "Positive Consequences" and "Negative Consequences" are merged together.
- Merging the
adr/folder with thedocs/folder could help people find information on our standards and why they exist more easily. - Meaningless
index.mdfiles are renamed toREADME.md, which is much more common.
Additionally to this format, links in ADR files should be written using the Reference style (for example: [0]: https://example.com) at the end of the document. In almost all cases, it makes it easier to read the plain Markdown text with no impact on the rendered HTML.
- Good, because it should improve the quality of future ADRs.
- Bad, because the
adr-logprogram (that we used to generate the links to each ADR) seems to choke on the YAML front-matter that is now part of the template (the top section, between---). As no new version has been released since 2020, and we are not willing to fork it or take up its maintenance, we choose to stop using it. New ADR links must be added manually to README pages.
All template.md files match the MADR v4.0.0 adr-template.md (the "full" template with all sections and explanations). There are no longer any adr/ folders. There are docs/decisions/ folders in all libraries, plugins or places that use ADR documents. The main files in each decisions/ folder are named README.md instead of index.md.
- MADR v4.0.0 Changelog
- Guidelines for folder structure and file names can be found here: https://adr.github.io/madr/#initialization
- Markdown Guide for Reference-style links
- This decision is expected to be revised/superseded in the future, for example if the MADR template is revised again, and it brings some improvement.