From 315c2e71eca6acb03f97771d17f6230fa2a86d28 Mon Sep 17 00:00:00 2001 From: Julius Walther Date: Mon, 22 Apr 2024 14:37:12 +0200 Subject: [PATCH] docs(all, ui-library): propose ADR format --- docs/ARCHITECTURE.md | 5 ++ .../README.md | 73 +++++++++++++++++++ .../assets/TEMPLATE.md | 69 ++++++++++++++++++ docs/architecture/decisions/README.md | 5 ++ .../docs/architecture/decisions/README.md | 5 ++ 5 files changed, 157 insertions(+) create mode 100644 docs/architecture/decisions/000-documenting-architecture-decisions/README.md create mode 100644 docs/architecture/decisions/000-documenting-architecture-decisions/assets/TEMPLATE.md create mode 100644 docs/architecture/decisions/README.md create mode 100644 packages/ui-library/docs/architecture/decisions/README.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 69b6bb009..bcf73c770 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -8,6 +8,7 @@ The BO1LER, a fully customisable design system (DS), is developed using the [Lit - [File Structure](#file-structure) - [Version Control](#version-control) - [Documentation and Testing](#documentation-and-testing) + - [Architecture Decision Records](#architecture-decision-records) - [CI/CD](#ci-cd) - [Technical Decisions](#technical-decisions) - [Web Components](#web-components) @@ -55,6 +56,10 @@ The code base, hosted on GitHub and maintained by the Deven team, is publicly ac ### Documentation and Testing The project adheres to best practices for documentation, and testing. The codebase is thoroughly documented with live preview capability and explicit guidelines on usage and contribution procedures. Additionally, comprehensive component tests are integrated to verify that modifications uphold the project's integrity and functionality, preventing regressions or defects from emerging. +#### Architecture Decision Records +Architectural decisions for this project are documented in the form of ADRs within this repository. +For more information check out: [000-documenting-architecture-decisions](./architecture/decisions/000-documenting-architecture-decisions/README.md#decision-outcome). For a list of all past architectural decisions check the [./architecture/decisions](./architecture/decisions) directory. + ### CI-CD The changes made in project's code base adheres to a continuous integration and delivery (CI/CD) pipeline. This guarantees that any alterations undergo rigorous testing and validation before being released to the production environment. diff --git a/docs/architecture/decisions/000-documenting-architecture-decisions/README.md b/docs/architecture/decisions/000-documenting-architecture-decisions/README.md new file mode 100644 index 000000000..50d7722cd --- /dev/null +++ b/docs/architecture/decisions/000-documenting-architecture-decisions/README.md @@ -0,0 +1,73 @@ +# Documenting Architecture Decisions + +* **Status:** proposed +* **Date:** 2024-04-19 +* **Deciders:** @faselbaum, @ChristianHoffmannS2, @angsherpa456 +* **Informed:** @thrbnhrtmnn + +## Context and Problem Statement +Excerpt from Michael Nygard - [DOCUMENTING ARCHITECTURE DECISIONS](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) + +> Architecture for agile projects has to be described and defined differently. Not all decisions will be made at once, nor will all of them be done when the project begins. +> +> Agile methods are not opposed to documentation, only to valueless documentation. Documents that assist the team itself can have value, but only if they are kept up to date. Large documents are never kept up to date. Small, modular documents have at least a chance at being updated. +> +> Nobody ever reads large documents, either. Most developers have been on at least one project where the specification document was larger (in bytes) than the total source code size. Those documents are too large to open, read, or update. Bite sized pieces are easier for for all stakeholders to consume. +> +> One of the hardest things to track during the life of a project is the motivation behind certain decisions. A new person coming on to a project may be perplexed, baffled, delighted, or infuriated by some past decision. Without understanding the rationale or consequences, this person has only two choices: +> +> ### 1. Blindly accept the decision. +> +> This response may be OK, if the decision is still valid. It may not be good, however, if the context has changed and the decision should really be revisited. If the project accumulates too many decisions accepted without understanding, then the development team becomes afraid to change anything and the project collapses under its own weight. +> +> ### 2. Blindly change it. +> +> Again, this may be OK if the decision needs to be reversed. On the other hand, changing the decision without understanding its motivation or consequences could mean damaging the project's overall value without realizing it. (E.g., the decision supported a non-functional requirement that hasn't been tested yet.) +> +> It's better to avoid either blind acceptance or blind reversal. + +## Decision Outcome + +> **📍 Document architecture decisions in the repository** + +We chose this option to ensure that decisions will not be overturned or accepted blindly. We want to provide collaborators with all the context needed to make well informed architectural decisions in the future. Remember: These decisions rarely stand on their own and will impact the course of other decisions throughout a projects lifecycle. + +Since the target audience for these decision records consists primarily of software engineers, we chose to store those documents locally within the repository as Markdown files so that they are accessible together with the code which they shape. + +To easily author, find and understand architectural decisions we adhere to a common format. + +### Format Description +Each decision is documented in a separate folder inside [/docs/architecture/decisions](/docs/architecture/decisions) **OR** inside `//docs/architecture/decisions` if the decision is only relevant for that package. + +#### Folder Name Format (regex) +```regex +(?\d{3})(?-)(?.+) +``` + +Note: The `sequencenumber` is scoped to each package. + +#### Folder Structure +```ini +. +├── README.md # The decision document. +└── assets # Optional. Referenced images / assets go here. +``` + +#### Document Structure +The general structure for each decision document is based on our [ADR Template](./assets/TEMPLATE.md). + +## Decision Drivers +* decision retraceability +* supports contributor onboarding +* consistency +* long term health of the project +* follow proven software design practices + +## Considered Options +* Do not document architecture decisions +* Document architecture decisions on GitHub Wiki +* Document architecture decisions in the repository + +## More Information +- [Architecture decision record (ADR) examples for software planning, IT leadership, and template documentation](https://github.com/joelparkerhenderson/architecture-decision-record) +- [Has Your Architectural Decision Record Lost Its Purpose?](https://www.infoq.com/articles/architectural-decision-record-purpose) diff --git a/docs/architecture/decisions/000-documenting-architecture-decisions/assets/TEMPLATE.md b/docs/architecture/decisions/000-documenting-architecture-decisions/assets/TEMPLATE.md new file mode 100644 index 000000000..9a64352a4 --- /dev/null +++ b/docs/architecture/decisions/000-documenting-architecture-decisions/assets/TEMPLATE.md @@ -0,0 +1,69 @@ +# {short title of solved problem and solution} + + +* **Status:** {proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)} +* **Date:** {YYYY-MM-DD when the decision was last updated} +* **Deciders:** {@github-user-1, @github-user-2, …} +* **Consulted:** {@github-user-1, @github-user-2, …} +* **Informed:** {@github-user-1, @github-user-2, …} + +## 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 Outcome + +> **📍 {title of chosen option}** + +{justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}. + + +## 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} +* … + + +### 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 a eslint rule.} + + +## 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/architecture/decisions/README.md b/docs/architecture/decisions/README.md new file mode 100644 index 000000000..388c9e4f9 --- /dev/null +++ b/docs/architecture/decisions/README.md @@ -0,0 +1,5 @@ +# Architectural Decisions +In this directory we document architectural decisions which are generally applicable to the project in the form of [ADRs (Architecture Decision Records)](https://github.com/joelparkerhenderson/architecture-decision-record). + +# More Information +[000-documenting-architecture-decisions](./000-documenting-architecture-decisions/README.md) diff --git a/packages/ui-library/docs/architecture/decisions/README.md b/packages/ui-library/docs/architecture/decisions/README.md new file mode 100644 index 000000000..6f0c7604d --- /dev/null +++ b/packages/ui-library/docs/architecture/decisions/README.md @@ -0,0 +1,5 @@ +# Architectural Decisions +In this directory we document architectural decisions which apply to this package in the form of [ADRs (Architecture Decision Records)](https://github.com/joelparkerhenderson/architecture-decision-record). + +# More Information +[000-documenting-architecture-decisions](/docs/architecture/decisions/000-documenting-architecture-decisions/README.md)