From 3b2c094e5a6cfa57d39bbe9c262f493650c46441 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Thu, 29 Aug 2024 09:50:05 +0200 Subject: [PATCH] Update to MADR 4.0.0 --- ...0000-use-architectural-decision-records.md | 21 ----- ...kdown-architectural-decision-records.md.md | 26 ++++++ docs/adr/0002-use-source-retention.md | 9 ++- docs/adr/adr-template.md | 79 +++++++++++++++++++ docs/adr/template.md | 42 ---------- 5 files changed, 110 insertions(+), 67 deletions(-) delete mode 100644 docs/adr/0000-use-architectural-decision-records.md create mode 100644 docs/adr/0000-use-markdown-architectural-decision-records.md.md create mode 100644 docs/adr/adr-template.md delete mode 100644 docs/adr/template.md diff --git a/docs/adr/0000-use-architectural-decision-records.md b/docs/adr/0000-use-architectural-decision-records.md deleted file mode 100644 index 926c899..0000000 --- a/docs/adr/0000-use-architectural-decision-records.md +++ /dev/null @@ -1,21 +0,0 @@ -# Use Markdown Architectural Decision Records (madr) - -Should we record the architectural decisions made in this project? -And if we do, wow to structure these recordings? - -## Considered Alternatives - -* [madr](https://github.com/adr/madr) - Markdown Architectural Decision Records -* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) - The first incarnation of the term "ADR". Maintainable by [adr-tools](https://github.com/npryce/adr-tools). -* [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) - The Y-Statements -* [DecisionRecord](https://github.com/schubmat/DecisionCapture) - Agile records by [@schubmat](https://github.com/schubmat/) -* Other templates listed at -* No records - -## Decision Outcome - -* Chosen Alternative: madr -* The madr template is lean and fits our development style. - Eat your own cookies. - - diff --git a/docs/adr/0000-use-markdown-architectural-decision-records.md.md b/docs/adr/0000-use-markdown-architectural-decision-records.md.md new file mode 100644 index 0000000..914b1e9 --- /dev/null +++ b/docs/adr/0000-use-markdown-architectural-decision-records.md.md @@ -0,0 +1,26 @@ +# Use Markdown Architectural Decision Records + +## Context and Problem Statement + +We want to record architectural 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/) 4.0.0 – The Markdown Architectural 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 4.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/0002-use-source-retention.md b/docs/adr/0002-use-source-retention.md index 0321fc8..c8d21f4 100644 --- a/docs/adr/0002-use-source-retention.md +++ b/docs/adr/0002-use-source-retention.md @@ -1,8 +1,10 @@ # Use Runtime Retention for the Annotations +## Context and Problem Statement + Which retention policy to use for `@ADR` annotations? -## Considered Alternatives +## Considered Options - [RetentionPolicy.RUNTIME](https://docs.oracle.com/javase/8/docs/api/java/lang/annotation/RetentionPolicy.html#RUNTIME) - [RetentionPolicy.CLASS](https://docs.oracle.com/javase/8/docs/api/java/lang/annotation/RetentionPolicy.html#CLASS) @@ -10,10 +12,9 @@ Which retention policy to use for `@ADR` annotations? ## Decision Outcome -- *Chosen Alternative: RetentionPolicy.SOURCE* -- We do not need the annotations during runtime. The byte code should be unchanged. +Chosen option: "RetentionPolicy.RUNTIME", because, we do not need the annotations during runtime. The byte code should be unchanged. -Further reading +## More Information - - diff --git a/docs/adr/adr-template.md b/docs/adr/adr-template.md new file mode 100644 index 0000000..6bfdedd --- /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} +decision-makers: {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, …} +* … + + +### Confirmation + +{Describe how the implementation of/compliance with the ADR is confirmed. E.g., by a review or an ArchUnit test. +Although we classify this element as optional, it is included in most ADRs.} + + +## 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/how this decision the decision should be realized and if/when it should be re-visited. +Links to other decisions and resources might appear here as well.} diff --git a/docs/adr/template.md b/docs/adr/template.md deleted file mode 100644 index e043387..0000000 --- a/docs/adr/template.md +++ /dev/null @@ -1,42 +0,0 @@ -# *[short title of solved problem and solution]* - -**User Story:** *[ticket/issue-number]* - -*[context and problem statement]* -*[decision drivers | forces]* - -## Considered Alternatives - -* *[alternative 1]* -* *[alternative 2]* -* *[alternative 3]* -* *[...]* - -## Decision Outcome - -* Chosen Alternative: *[alternative 1]* -* *[justification. e.g., only alternative, which meets k.o. criterion decision driver | which resolves force force | ... | comes out best (see below)]* -* *[consequences. e.g., negative impact on quality attribute, follow-up decisions required, ...]* - -## Pros and Cons of the Alternatives - -### *[alternative 1]* - -* `+` *[argument 1 pro]* -* `+` *[argument 2 pro]* -* `-` *[argument 1 con]* -* *[...]* - -### *[alternative 2]* - -* `+` *[argument 1 pro]* -* `+` *[argument 2 pro]* -* `-` *[argument 1 con]* -* *[...]* - -### *[alternative 3]* - -* `+` *[argument 1 pro]* -* `+` *[argument 2 pro]* -* `-` *[argument 1 con]* -* *[...]*