From 6611e70d0b0dddd52bcab12a0696c3d8f9e2108b Mon Sep 17 00:00:00 2001 From: "Allen D. Householder" Date: Thu, 19 Oct 2023 14:36:05 -0400 Subject: [PATCH] add ADR folder, exclude from site publication (#13) * add ADR folder, exclude from site publication * update to MADR 3.0.0 --- .gitignore | 3 + .../adr/0000-record-architecture-decisions.md | 18 +++++ .../0001-use-markdown-any-decision-records.md | 31 ++++++++ docs/adr/README.md | 7 ++ docs/adr/adr-template.md | 79 +++++++++++++++++++ mkdocs.yml | 2 + 6 files changed, 140 insertions(+) create mode 100644 docs/adr/0000-record-architecture-decisions.md create mode 100644 docs/adr/0001-use-markdown-any-decision-records.md create mode 100644 docs/adr/README.md create mode 100644 docs/adr/adr-template.md diff --git a/.gitignore b/.gitignore index 9b5c2c1e..ecd1fe9c 100644 --- a/.gitignore +++ b/.gitignore @@ -132,3 +132,6 @@ dmypy.json # generated by setuptools_scm /vultron/_version.py +/node_modules/ +/package.json +/package-lock.json diff --git a/docs/adr/0000-record-architecture-decisions.md b/docs/adr/0000-record-architecture-decisions.md new file mode 100644 index 00000000..d88b5946 --- /dev/null +++ b/docs/adr/0000-record-architecture-decisions.md @@ -0,0 +1,18 @@ +--- +status: accepted +date: 2023-10-18 +deciders: adh +--- +# Record architecture decisions + +## Context + +We need to record the architectural decisions made on Opinionated Digital Center. + +## Decision + +We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). + +## Consequences + +See Michael Nygard's article, linked above. diff --git a/docs/adr/0001-use-markdown-any-decision-records.md b/docs/adr/0001-use-markdown-any-decision-records.md new file mode 100644 index 00000000..a3294782 --- /dev/null +++ b/docs/adr/0001-use-markdown-any-decision-records.md @@ -0,0 +1,31 @@ +--- +status: accepted +date: 2023-10-18 +deciders: adh +--- +# 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" +* [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements +* Other templates listed at +* 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. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 00000000..04664068 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,7 @@ +# Decisions + +This directory contains decision records for {project name}. + +For new ADRs, please use [adr-template.md](adr-template.md) as basis. +More information on MADR is available at . +General information about architectural decision records is available at . diff --git a/docs/adr/adr-template.md b/docs/adr/adr-template.md new file mode 100644 index 00000000..054289ad --- /dev/null +++ b/docs/adr/adr-template.md @@ -0,0 +1,79 @@ +--- +# 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.} + + +## Decision Drivers + +* {decision driver 1, e.g., a force, facing concern, …} +* {decision driver 2, e.g., a force, facing concern, …} +* … + +## Considered Options + +* {title of option 1} +* {title of option 2} +* {title of option 3} +* … + +## 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)}. + + +### 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, …} +* … + + +## Validation + +{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test} + + +## Pros and Cons of the Options + +### {title of option 1} + + +{example | description | pointer to more information | …} + +* Good, because {argument a} +* Good, because {argument b} + +* Neutral, because {argument c} +* Bad, because {argument d} +* … + +### {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} +* … + + +## 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.} diff --git a/mkdocs.yml b/mkdocs.yml index d10e9441..a72651c2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -228,3 +228,5 @@ extra_javascript: - javascripts/tablesort.js extra_css: - stylesheets/extra.css +exclude_docs: | + /adr/