diff --git a/.github/workflows/push_request_check.yml b/.github/workflows/push_request_check.yml index e777cafb..35877a86 100644 --- a/.github/workflows/push_request_check.yml +++ b/.github/workflows/push_request_check.yml @@ -5,6 +5,8 @@ on: branches: [ main ] pull_request: branches: [ '**' ] + paths-ignore: + - 'documentation/decisions/**' # Tests are done in Ubuntu because Mac and Windows random failures, and it is not stable. jobs: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 34ef663a..c2a14ee7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,10 @@ Model (SAMM) and supports its use. * For discussions specific to development, the preferred way is the [developer mailing list](https://accounts.eclipse.org/mailing-list/esmf-dev). +## Architecture Decision Records + +Decisions on code and architecture are documented using [Markdown Any Decision +Records](https://adr.github.io/madr/) in [documentation/decisions/](https://github.com/eclipse-esmf/esmf-aspect-model-editor/tree/main/documentation/decisions). ## Branching We follow diff --git a/documentation/decisions/0000-use-markdown-any-decision-records.md b/documentation/decisions/0000-use-markdown-any-decision-records.md new file mode 100644 index 00000000..0edc15d6 --- /dev/null +++ b/documentation/decisions/0000-use-markdown-any-decision-records.md @@ -0,0 +1,26 @@ +# 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/documentation/decisions/README.md b/documentation/decisions/README.md new file mode 100644 index 00000000..3e0927e9 --- /dev/null +++ b/documentation/decisions/README.md @@ -0,0 +1,7 @@ +# Decisions + +This directory contains decision records for esmf-aspect-model-editor. + +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/documentation/decisions/adr-template.md b/documentation/decisions/adr-template.md new file mode 100644 index 00000000..054289ad --- /dev/null +++ b/documentation/decisions/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.}