Use Markdown Any Decision Records
24-01-2024
../adr_madr3_example/0001-record-architecture-decisions.md
Statuses:
3. Supercedes 1-b
22-01-2024
../adr_nygard_example/0003-supercedes-1-b.md
Accepted
Supercedes 1. Record architecture decisions
2. Supercedes 1
../adr_nygard_example/0002-supercedes-1.md
1. Record architecture decisions
20-01-2024
../adr_nygard_example/0001-record-architecture-decisions.md
Superceded by 2. Supersedes 1
Superceded by 3. Supersedes 1-b
Enable the plugin in mkdocs.yml
mkdocs.yml
plugins: - macros: - module_name: mkdocs_macros_adr_summary + modules: + - mkdocs_macros_adr_summary
Create a markdown page in your mkdocs website and use the adr_summary macro providing the path containing your ADR files relative to the mkdocs.yml file.
adr_summary
{{ adr_summary(adr_path="docs/adr", adr_style="MADR3", template_file="other.jinja") }}
The default template is:
## Document list - -{% for d in documents %} -* [{{ d.title }}]({{ d.filename }}) - * `{{ d.date.strftime('%d-%m-%Y') }}` - * `{{ d.file_path }}` - {% if d.statuses %} - * Statuses: - {% for status in d.statuses %} - * {{ status }} - {% endfor %} - {% endif %} +| Date | Decision | Status | +|------|----------|--------| +{% for d in documents %}| {{ d.date.strftime('%d-%m-%Y') }} | [{{ d.title }}]({{ d.filename }}) | {{ d.status }} | {% endfor %} The documents variable in the jinja template is a Sequence of ADRDocument models: diff --git a/0.1/search/search_index.json b/0.1/search/search_index.json index 48d40cf..c68e492 100644 --- a/0.1/search/search_index.json +++ b/0.1/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"mkdocs-macros-adr-summary","text":"This is a macro plugin to generates summaries from a list of a ADR documents in a directory. Examples and documentation can be found here 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."},{"location":"#quick-start","title":"Quick start","text":"Enable the plugin in mkdocs.yml plugins:\n - macros:\n module_name: mkdocs_macros_adr_summary\n Create a markdown page in your mkdocs website and use the adr_summary macro providing the path containing your ADR files relative to the mkdocs.yml file. {{ adr_summary(adr_path=\"docs/adr\", adr_style=\"nygard\") }}\n adr_style can be nygard or MADR3"},{"location":"#more-customization","title":"More customization","text":"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. {{ adr_summary(adr_path=\"docs/adr\", adr_style=\"MADR3\", template_file=\"other.jinja\") }}\n The default template is: ## Document list\n\n{% for d in documents %}\n* [{{ d.title }}]({{ d.filename }})\n * `{{ d.date.strftime('%d-%m-%Y') }}`\n * `{{ d.file_path }}`\n {% if d.statuses %}\n * Statuses:\n {% for status in d.statuses %}\n * {{ status }}\n {% endfor %}\n {% endif %}\n{% endfor %}\n The documents variable in the jinja template is a Sequence of ADRDocument models: @dataclass\nclass ADRDocument:\n file_path: str\n title: Optional[str] = None\n date: Optional[date] = None\n stasdetus: Optional[str] = None\n statuses: Sequence[str] = tuple()\n deciders: Optional[str] = None\n consulted: Optional[str] = None\n informed: Optional[str] = None\n There are some differences in what metadata is available when using different formats: Nygard MADR3 MADR2 file_path \u2705\ufe0e \u2705\ufe0e \u2705\ufe0e title \u2705\ufe0e \u2705\ufe0e \u2705\ufe0e date \u2705\ufe0e \u2705\ufe0e TODO status \u26a0 \u2705\ufe0e TODO statuses \u2705\ufe0e \u26a0 TODO deciders \u274c \u2705\ufe0e TODO consulted \u274c \u2705\ufe0e TODO informed \u274c \u2705\ufe0e 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. "},{"location":"#supported-adr-formats","title":"Supported ADR formats","text":"The supported ADR formats are: * nygard format, it is recommended to use adr-tools to manage the directory * MADR version 3 Support for MADR version 2 will be added in a future version."},{"location":"#commands-for-development","title":"Commands for development","text":"All the common commands used during development can be run using make targets: make dev-dependencies: Install dev requirements make update-dependencies: Update dev requirements make test: Run test suite make check: Run tests, code style and lint checks make fix: Run code style and lint automatic fixes (where possible) make docs: Render the mkdocs website locally "},{"location":"adr_madr2_example/0001-record-architecture-decisions/","title":"Use Markdown Any Decision Records","text":""},{"location":"adr_madr2_example/0001-record-architecture-decisions/#context-and-problem-statement","title":"Context and Problem Statement","text":"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?"},{"location":"adr_madr2_example/0001-record-architecture-decisions/#considered-options","title":"Considered Options","text":" MADR 2.1.2 \u2013 The Markdown Any Decision Records Michael Nygard's template \u2013 The first incarnation of the term \"ADR\" Other templates listed at https://schubmat.github.io/DecisionCapture Formless \u2013 No conventions for file format and structure "},{"location":"adr_madr2_example/0001-record-architecture-decisions/#decision-outcome","title":"Decision Outcome","text":"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. 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. "},{"location":"adr_madr2_example/template/","title":"[short title of solved problem and solution] source: https://github.com/adr/madr/tree/2.1.2/template","text":" Status: [proposed | rejected | accepted | deprecated | \u2026 | superseded by ADR-0005] Deciders: [list everyone involved in the decision] Date: [YYYY-MM-DD when the decision was last updated] Technical Story: [description | ticket/issue URL] "},{"location":"adr_madr2_example/template/#context-and-problem-statement","title":"Context and Problem Statement","text":"[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.]"},{"location":"adr_madr2_example/template/#decision-drivers","title":"Decision Drivers","text":" [driver 1, e.g., a force, facing concern, \u2026] [driver 2, e.g., a force, facing concern, \u2026] \u2026 "},{"location":"adr_madr2_example/template/#considered-options","title":"Considered Options","text":" [option 1] [option 2] [option 3] \u2026 "},{"location":"adr_madr2_example/template/#decision-outcome","title":"Decision Outcome","text":"Chosen option: \"[option 1]\", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | \u2026 | comes out best (see below)]."},{"location":"adr_madr2_example/template/#positive-consequences","title":"Positive Consequences","text":" [e.g., improvement of quality attribute satisfaction, follow-up decisions required, \u2026] \u2026 "},{"location":"adr_madr2_example/template/#negative-consequences","title":"Negative Consequences","text":" [e.g., compromising quality attribute, follow-up decisions required, \u2026] \u2026 "},{"location":"adr_madr2_example/template/#pros-and-cons-of-the-options","title":"Pros and Cons of the Options","text":""},{"location":"adr_madr2_example/template/#option-1","title":"[option 1]","text":"[example | description | pointer to more information | \u2026] Good, because [argument a] Good, because [argument b] Bad, because [argument c] \u2026 "},{"location":"adr_madr2_example/template/#option-2","title":"[option 2]","text":"[example | description | pointer to more information | \u2026] Good, because [argument a] Good, because [argument b] Bad, because [argument c] \u2026 "},{"location":"adr_madr2_example/template/#option-3","title":"[option 3]","text":"[example | description | pointer to more information | \u2026] Good, because [argument a] Good, because [argument b] Bad, because [argument c] \u2026 "},{"location":"adr_madr2_example/template/#links","title":"Links","text":" [Link type] [Link to ADR] \u2026 "},{"location":"adr_madr3_example/0001-record-architecture-decisions/","title":"Use Markdown Any Decision Records","text":""},{"location":"adr_madr3_example/0001-record-architecture-decisions/#context-and-problem-statement","title":"Context and Problem Statement","text":"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?"},{"location":"adr_madr3_example/0001-record-architecture-decisions/#considered-options","title":"Considered Options","text":" MADR 3.0.0 \u2013 The Markdown Any Decision Records Michael Nygard's template \u2013 The first incarnation of the term \"ADR\" Other templates listed at https://schubmat.github.io/DecisionCapture Formless \u2013 No conventions for file format and structure "},{"location":"adr_madr3_example/0001-record-architecture-decisions/#decision-outcome","title":"Decision Outcome","text":"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. 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. "},{"location":"adr_madr3_example/adr-template/","title":"Adr template","text":""},{"location":"adr_madr3_example/adr-template/#source-httpsgithubcomadrmadrblob300templateadr-templatemd","title":"source: https://github.com/adr/madr/blob/3.0.0/template/adr-template.md","text":""},{"location":"adr_madr3_example/adr-template/#these-are-optional-elements-feel-free-to-remove-any-of-them","title":"These are optional elements. Feel free to remove any of them.","text":"status: {proposed | rejected | accepted | deprecated | \u2026 | superseded by ADR-0005} 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}"},{"location":"adr_madr3_example/adr-template/#short-title-of-solved-problem-and-solution","title":"{short title of solved problem and solution}","text":""},{"location":"adr_madr3_example/adr-template/#context-and-problem-statement","title":"Context and Problem Statement","text":"{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.}"},{"location":"adr_madr3_example/adr-template/#decision-drivers","title":"Decision Drivers","text":" {decision driver 1, e.g., a force, facing concern, \u2026} {decision driver 2, e.g., a force, facing concern, \u2026} \u2026 "},{"location":"adr_madr3_example/adr-template/#considered-options","title":"Considered Options","text":" {title of option 1} {title of option 2} {title of option 3} \u2026 "},{"location":"adr_madr3_example/adr-template/#decision-outcome","title":"Decision Outcome","text":"Chosen option: \"{title of option 1}\", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | \u2026 | comes out best (see below)}."},{"location":"adr_madr3_example/adr-template/#consequences","title":"Consequences","text":" Good, because {positive consequence, e.g., improvement of one or more desired qualities, \u2026} Bad, because {negative consequence, e.g., compromising one or more desired qualities, \u2026} \u2026 "},{"location":"adr_madr3_example/adr-template/#validation","title":"Validation","text":"{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test}"},{"location":"adr_madr3_example/adr-template/#pros-and-cons-of-the-options","title":"Pros and Cons of the Options","text":""},{"location":"adr_madr3_example/adr-template/#title-of-option-1","title":"{title of option 1}","text":"{example | description | pointer to more information | \u2026} Good, because {argument a} Good, because {argument b} Neutral, because {argument c} Bad, because {argument d} \u2026 "},{"location":"adr_madr3_example/adr-template/#title-of-other-option","title":"{title of other option}","text":"{example | description | pointer to more information | \u2026} Good, because {argument a} Good, because {argument b} Neutral, because {argument c} Bad, because {argument d} \u2026 "},{"location":"adr_madr3_example/adr-template/#more-information","title":"More Information","text":"{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.}"},{"location":"adr_madr3_example/summary/","title":"Summary","text":""},{"location":"adr_madr3_example/summary/#document-list","title":"Document list","text":" Use Markdown Any Decision Records 24-01-2024 ../adr_madr3_example/0001-record-architecture-decisions.md Statuses: Accepted "},{"location":"adr_nygard_example/0001-record-architecture-decisions/","title":"1. Record architecture decisions","text":"Date: 2024-01-20"},{"location":"adr_nygard_example/0001-record-architecture-decisions/#status","title":"Status","text":"Superceded by 2. Supersedes 1 Superceded by 3. Supersedes 1-b"},{"location":"adr_nygard_example/0001-record-architecture-decisions/#context","title":"Context","text":"We need to record the architectural decisions made on this project."},{"location":"adr_nygard_example/0001-record-architecture-decisions/#decision","title":"Decision","text":"We will use Architecture Decision Records, as described by Michael Nygard."},{"location":"adr_nygard_example/0001-record-architecture-decisions/#consequences","title":"Consequences","text":"See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's adr-tools."},{"location":"adr_nygard_example/0002-supercedes-1/","title":"2. Supercedes 1","text":"Date: 2024-01-22"},{"location":"adr_nygard_example/0002-supercedes-1/#status","title":"Status","text":"Accepted Supercedes 1. Record architecture decisions"},{"location":"adr_nygard_example/0002-supercedes-1/#context","title":"Context","text":"The issue motivating this decision, and any context that influences or constrains the decision."},{"location":"adr_nygard_example/0002-supercedes-1/#decision","title":"Decision","text":"The change that we're proposing or have agreed to implement."},{"location":"adr_nygard_example/0002-supercedes-1/#consequences","title":"Consequences","text":"What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated."},{"location":"adr_nygard_example/0003-supercedes-1-b/","title":"3. Supercedes 1-b","text":"Date: 2024-01-22"},{"location":"adr_nygard_example/0003-supercedes-1-b/#status","title":"Status","text":"Accepted Supercedes 1. Record architecture decisions"},{"location":"adr_nygard_example/0003-supercedes-1-b/#context","title":"Context","text":"The issue motivating this decision, and any context that influences or constrains the decision."},{"location":"adr_nygard_example/0003-supercedes-1-b/#decision","title":"Decision","text":"The change that we're proposing or have agreed to implement."},{"location":"adr_nygard_example/0003-supercedes-1-b/#consequences","title":"Consequences","text":"What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated."},{"location":"adr_nygard_example/summary/","title":"Summary","text":""},{"location":"adr_nygard_example/summary/#document-list","title":"Document list","text":" 3. Supercedes 1-b 22-01-2024 ../adr_nygard_example/0003-supercedes-1-b.md Statuses: Accepted Supercedes 1. Record architecture decisions 2. Supercedes 1 22-01-2024 ../adr_nygard_example/0002-supercedes-1.md Statuses: Accepted Supercedes 1. Record architecture decisions 1. Record architecture decisions 20-01-2024 ../adr_nygard_example/0001-record-architecture-decisions.md Statuses: Superceded by 2. Supersedes 1 Superceded by 3. Supersedes 1-b "}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"mkdocs-macros-adr-summary","text":"This is a macro plugin to generates summaries from a list of a ADR documents in a directory. Examples and documentation can be found here 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."},{"location":"#quick-start","title":"Quick start","text":"Enable the plugin in mkdocs.yml plugins:\n - macros:\n modules:\n - mkdocs_macros_adr_summary\n Create a markdown page in your mkdocs website and use the adr_summary macro providing the path containing your ADR files relative to the mkdocs.yml file. {{ adr_summary(adr_path=\"docs/adr\", adr_style=\"nygard\") }}\n adr_style can be nygard or MADR3"},{"location":"#more-customization","title":"More customization","text":"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. {{ adr_summary(adr_path=\"docs/adr\", adr_style=\"MADR3\", template_file=\"other.jinja\") }}\n The default template is: | Date | Decision | Status |\n|------|----------|--------|\n{% for d in documents %}| {{ d.date.strftime('%d-%m-%Y') }} | [{{ d.title }}]({{ d.filename }}) | {{ d.status }} |\n{% endfor %}\n The documents variable in the jinja template is a Sequence of ADRDocument models: @dataclass\nclass ADRDocument:\n file_path: str\n title: Optional[str] = None\n date: Optional[date] = None\n stasdetus: Optional[str] = None\n statuses: Sequence[str] = tuple()\n deciders: Optional[str] = None\n consulted: Optional[str] = None\n informed: Optional[str] = None\n There are some differences in what metadata is available when using different formats: Nygard MADR3 MADR2 file_path \u2705\ufe0e \u2705\ufe0e \u2705\ufe0e title \u2705\ufe0e \u2705\ufe0e \u2705\ufe0e date \u2705\ufe0e \u2705\ufe0e TODO status \u26a0 \u2705\ufe0e TODO statuses \u2705\ufe0e \u26a0 TODO deciders \u274c \u2705\ufe0e TODO consulted \u274c \u2705\ufe0e TODO informed \u274c \u2705\ufe0e 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. "},{"location":"#supported-adr-formats","title":"Supported ADR formats","text":"The supported ADR formats are: * nygard format, it is recommended to use adr-tools to manage the directory * MADR version 3 Support for MADR version 2 will be added in a future version."},{"location":"#commands-for-development","title":"Commands for development","text":"All the common commands used during development can be run using make targets: make dev-dependencies: Install dev requirements make update-dependencies: Update dev requirements make test: Run test suite make check: Run tests, code style and lint checks make fix: Run code style and lint automatic fixes (where possible) make docs: Render the mkdocs website locally "},{"location":"adr_madr2_example/0001-record-architecture-decisions/","title":"Use Markdown Any Decision Records","text":""},{"location":"adr_madr2_example/0001-record-architecture-decisions/#context-and-problem-statement","title":"Context and Problem Statement","text":"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?"},{"location":"adr_madr2_example/0001-record-architecture-decisions/#considered-options","title":"Considered Options","text":" MADR 2.1.2 \u2013 The Markdown Any Decision Records Michael Nygard's template \u2013 The first incarnation of the term \"ADR\" Other templates listed at https://schubmat.github.io/DecisionCapture Formless \u2013 No conventions for file format and structure "},{"location":"adr_madr2_example/0001-record-architecture-decisions/#decision-outcome","title":"Decision Outcome","text":"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. 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. "},{"location":"adr_madr2_example/template/","title":"[short title of solved problem and solution] source: https://github.com/adr/madr/tree/2.1.2/template","text":" Status: [proposed | rejected | accepted | deprecated | \u2026 | superseded by ADR-0005] Deciders: [list everyone involved in the decision] Date: [YYYY-MM-DD when the decision was last updated] Technical Story: [description | ticket/issue URL] "},{"location":"adr_madr2_example/template/#context-and-problem-statement","title":"Context and Problem Statement","text":"[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.]"},{"location":"adr_madr2_example/template/#decision-drivers","title":"Decision Drivers","text":" [driver 1, e.g., a force, facing concern, \u2026] [driver 2, e.g., a force, facing concern, \u2026] \u2026 "},{"location":"adr_madr2_example/template/#considered-options","title":"Considered Options","text":" [option 1] [option 2] [option 3] \u2026 "},{"location":"adr_madr2_example/template/#decision-outcome","title":"Decision Outcome","text":"Chosen option: \"[option 1]\", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | \u2026 | comes out best (see below)]."},{"location":"adr_madr2_example/template/#positive-consequences","title":"Positive Consequences","text":" [e.g., improvement of quality attribute satisfaction, follow-up decisions required, \u2026] \u2026 "},{"location":"adr_madr2_example/template/#negative-consequences","title":"Negative Consequences","text":" [e.g., compromising quality attribute, follow-up decisions required, \u2026] \u2026 "},{"location":"adr_madr2_example/template/#pros-and-cons-of-the-options","title":"Pros and Cons of the Options","text":""},{"location":"adr_madr2_example/template/#option-1","title":"[option 1]","text":"[example | description | pointer to more information | \u2026] Good, because [argument a] Good, because [argument b] Bad, because [argument c] \u2026 "},{"location":"adr_madr2_example/template/#option-2","title":"[option 2]","text":"[example | description | pointer to more information | \u2026] Good, because [argument a] Good, because [argument b] Bad, because [argument c] \u2026 "},{"location":"adr_madr2_example/template/#option-3","title":"[option 3]","text":"[example | description | pointer to more information | \u2026] Good, because [argument a] Good, because [argument b] Bad, because [argument c] \u2026 "},{"location":"adr_madr2_example/template/#links","title":"Links","text":" [Link type] [Link to ADR] \u2026 "},{"location":"adr_madr3_example/0001-record-architecture-decisions/","title":"Use Markdown Any Decision Records","text":""},{"location":"adr_madr3_example/0001-record-architecture-decisions/#context-and-problem-statement","title":"Context and Problem Statement","text":"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?"},{"location":"adr_madr3_example/0001-record-architecture-decisions/#considered-options","title":"Considered Options","text":" MADR 3.0.0 \u2013 The Markdown Any Decision Records Michael Nygard's template \u2013 The first incarnation of the term \"ADR\" Other templates listed at https://schubmat.github.io/DecisionCapture Formless \u2013 No conventions for file format and structure "},{"location":"adr_madr3_example/0001-record-architecture-decisions/#decision-outcome","title":"Decision Outcome","text":"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. 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. "},{"location":"adr_madr3_example/adr-template/","title":"Adr template","text":""},{"location":"adr_madr3_example/adr-template/#source-httpsgithubcomadrmadrblob300templateadr-templatemd","title":"source: https://github.com/adr/madr/blob/3.0.0/template/adr-template.md","text":""},{"location":"adr_madr3_example/adr-template/#these-are-optional-elements-feel-free-to-remove-any-of-them","title":"These are optional elements. Feel free to remove any of them.","text":"status: {proposed | rejected | accepted | deprecated | \u2026 | superseded by ADR-0005} 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}"},{"location":"adr_madr3_example/adr-template/#short-title-of-solved-problem-and-solution","title":"{short title of solved problem and solution}","text":""},{"location":"adr_madr3_example/adr-template/#context-and-problem-statement","title":"Context and Problem Statement","text":"{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.}"},{"location":"adr_madr3_example/adr-template/#decision-drivers","title":"Decision Drivers","text":" {decision driver 1, e.g., a force, facing concern, \u2026} {decision driver 2, e.g., a force, facing concern, \u2026} \u2026 "},{"location":"adr_madr3_example/adr-template/#considered-options","title":"Considered Options","text":" {title of option 1} {title of option 2} {title of option 3} \u2026 "},{"location":"adr_madr3_example/adr-template/#decision-outcome","title":"Decision Outcome","text":"Chosen option: \"{title of option 1}\", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | \u2026 | comes out best (see below)}."},{"location":"adr_madr3_example/adr-template/#consequences","title":"Consequences","text":" Good, because {positive consequence, e.g., improvement of one or more desired qualities, \u2026} Bad, because {negative consequence, e.g., compromising one or more desired qualities, \u2026} \u2026 "},{"location":"adr_madr3_example/adr-template/#validation","title":"Validation","text":"{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test}"},{"location":"adr_madr3_example/adr-template/#pros-and-cons-of-the-options","title":"Pros and Cons of the Options","text":""},{"location":"adr_madr3_example/adr-template/#title-of-option-1","title":"{title of option 1}","text":"{example | description | pointer to more information | \u2026} Good, because {argument a} Good, because {argument b} Neutral, because {argument c} Bad, because {argument d} \u2026 "},{"location":"adr_madr3_example/adr-template/#title-of-other-option","title":"{title of other option}","text":"{example | description | pointer to more information | \u2026} Good, because {argument a} Good, because {argument b} Neutral, because {argument c} Bad, because {argument d} \u2026 "},{"location":"adr_madr3_example/adr-template/#more-information","title":"More Information","text":"{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.}"},{"location":"adr_madr3_example/summary/","title":"ADR Summary","text":"Date Decision Status 24-01-2024 Use Markdown Any Decision Records Accepted"},{"location":"adr_nygard_example/0001-record-architecture-decisions/","title":"1. Record architecture decisions","text":"Date: 2024-01-20"},{"location":"adr_nygard_example/0001-record-architecture-decisions/#status","title":"Status","text":"Superceded by 2. Supersedes 1 Superceded by 3. Supersedes 1-b"},{"location":"adr_nygard_example/0001-record-architecture-decisions/#context","title":"Context","text":"We need to record the architectural decisions made on this project."},{"location":"adr_nygard_example/0001-record-architecture-decisions/#decision","title":"Decision","text":"We will use Architecture Decision Records, as described by Michael Nygard."},{"location":"adr_nygard_example/0001-record-architecture-decisions/#consequences","title":"Consequences","text":"See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's adr-tools."},{"location":"adr_nygard_example/0002-supercedes-1/","title":"2. Supercedes 1","text":"Date: 2024-01-22"},{"location":"adr_nygard_example/0002-supercedes-1/#status","title":"Status","text":"Accepted Supercedes 1. Record architecture decisions"},{"location":"adr_nygard_example/0002-supercedes-1/#context","title":"Context","text":"The issue motivating this decision, and any context that influences or constrains the decision."},{"location":"adr_nygard_example/0002-supercedes-1/#decision","title":"Decision","text":"The change that we're proposing or have agreed to implement."},{"location":"adr_nygard_example/0002-supercedes-1/#consequences","title":"Consequences","text":"What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated."},{"location":"adr_nygard_example/0003-supercedes-1-b/","title":"3. Supercedes 1-b","text":"Date: 2024-01-22"},{"location":"adr_nygard_example/0003-supercedes-1-b/#status","title":"Status","text":"Accepted Supercedes 1. Record architecture decisions"},{"location":"adr_nygard_example/0003-supercedes-1-b/#context","title":"Context","text":"The issue motivating this decision, and any context that influences or constrains the decision."},{"location":"adr_nygard_example/0003-supercedes-1-b/#decision","title":"Decision","text":"The change that we're proposing or have agreed to implement."},{"location":"adr_nygard_example/0003-supercedes-1-b/#consequences","title":"Consequences","text":"What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated."},{"location":"adr_nygard_example/summary/","title":"ADR Summary","text":"Date Decision Status 20-01-2024 1. Record architecture decisions Superceded by 3. Supersedes 1-b 22-01-2024 2. Supercedes 1 Supercedes 1. Record architecture decisions 22-01-2024 3. Supercedes 1-b Supercedes 1. Record architecture decisions"}]} \ No newline at end of file diff --git a/0.1/sitemap.xml.gz b/0.1/sitemap.xml.gz index f4d6690..a286128 100644 Binary files a/0.1/sitemap.xml.gz and b/0.1/sitemap.xml.gz differ
| Date | Decision | Status | +|------|----------|--------| +{% for d in documents %}| {{ d.date.strftime('%d-%m-%Y') }} | [{{ d.title }}]({{ d.filename }}) | {{ d.status }} | {% endfor %}
The documents variable in the jinja template is a Sequence of ADRDocument models:
documents
ADRDocument
This is a macro plugin to generates summaries from a list of a ADR documents in a directory.
Examples and documentation can be found here
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.
plugins:\n - macros:\n module_name: mkdocs_macros_adr_summary\n
{{ adr_summary(adr_path=\"docs/adr\", adr_style=\"nygard\") }}\n
adr_style can be nygard or MADR3
adr_style
nygard
MADR3
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.
{{ adr_summary(adr_path=\"docs/adr\", adr_style=\"MADR3\", template_file=\"other.jinja\") }}\n
## Document list\n\n{% for d in documents %}\n* [{{ d.title }}]({{ d.filename }})\n * `{{ d.date.strftime('%d-%m-%Y') }}`\n * `{{ d.file_path }}`\n {% if d.statuses %}\n * Statuses:\n {% for status in d.statuses %}\n * {{ status }}\n {% endfor %}\n {% endif %}\n{% endfor %}\n
@dataclass\nclass ADRDocument:\n file_path: str\n title: Optional[str] = None\n date: Optional[date] = None\n stasdetus: Optional[str] = None\n statuses: Sequence[str] = tuple()\n deciders: Optional[str] = None\n consulted: Optional[str] = None\n informed: Optional[str] = None\n
There are some differences in what metadata is available when using different formats:
status
statuses
adr-tools
deciders
consulted
informed
The supported ADR formats are: * nygard format, it is recommended to use adr-tools to manage the directory * MADR version 3
MADR
Support for MADR version 2 will be added in a future version.
All the common commands used during development can be run using make targets:
make dev-dependencies
make update-dependencies
make test
make check
make fix
make docs
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?
Chosen option: \"MADR 2.1.2\", because
Technical Story: [description | ticket/issue URL]
[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.]
Chosen option: \"[option 1]\", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | \u2026 | comes out best (see below)].
[example | description | pointer to more information | \u2026]
Chosen option: \"MADR 3.0.0\", because
status: {proposed | rejected | accepted | deprecated | \u2026 | superseded by ADR-0005} 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}
{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.}
Chosen option: \"{title of option 1}\", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | \u2026 | comes out best (see below)}.
{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test}
{example | description | pointer to more information | \u2026}
{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.}
Date: 2024-01-20
We need to record the architectural decisions made on this project.
We will use Architecture Decision Records, as described by Michael Nygard.
See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's adr-tools.
Date: 2024-01-22
The issue motivating this decision, and any context that influences or constrains the decision.
The change that we're proposing or have agreed to implement.
What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.
plugins:\n - macros:\n modules:\n - mkdocs_macros_adr_summary\n
| Date | Decision | Status |\n|------|----------|--------|\n{% for d in documents %}| {{ d.date.strftime('%d-%m-%Y') }} | [{{ d.title }}]({{ d.filename }}) | {{ d.status }} |\n{% endfor %}\n