Skip to content

Commit 006bc6a

Browse files
faselbaumfaselbaum
committed
docs(all, ui-library): propose ADR format
1 parent ccb4e17 commit 006bc6a

File tree

5 files changed

+162
-0
lines changed

5 files changed

+162
-0
lines changed

‎docs/ARCHITECTURE.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ The BO1LER, a fully customisable design system (DS), is developed using the [Lit
88
- [File Structure](#file-structure)
99
- [Version Control](#version-control)
1010
- [Documentation and Testing](#documentation-and-testing)
11+
- [Architecture Decision Records](#architecture-decision-records)
1112
- [CI/CD](#ci-cd)
1213
- [Technical Decisions](#technical-decisions)
1314
- [Web Components](#web-components)
@@ -55,6 +56,10 @@ The code base, hosted on GitHub and maintained by the Deven team, is publicly ac
5556
### Documentation and Testing
5657
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.
5758

59+
#### Architecture Decision Records
60+
Architectural decisions for this project are documented in the form of ADRs within this repository.
61+
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.
62+
5863
### CI-CD
5964
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.
6065

‎docs/architecture/decisions/000-documenting-architecture-decisions/README.md

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Documenting Architecture Decisions
2+
3+
* **Status:** proposed
4+
* **Date:** 2024-04-19
5+
* **Deciders:** @faselbaum, @ChristianHoffmannS2, @angsherpa456
6+
* **Informed:** @thrbnhrtmnn
7+
8+
## Context and Problem Statement
9+
Excerpt from Michael Nygard - [DOCUMENTING ARCHITECTURE DECISIONS](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
10+
11+
> 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.
12+
>
13+
> 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.
14+
>
15+
> 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.
16+
>
17+
> 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:
18+
>
19+
> ### 1. Blindly accept the decision.
20+
>
21+
> 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.
22+
>
23+
> ### 2. Blindly change it.
24+
>
25+
> 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.)
26+
>
27+
> It's better to avoid either blind acceptance or blind reversal.
28+
29+
## Decision Outcome
30+
31+
> **📍 Document architecture decisions in the repository**
32+
33+
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.
34+
35+
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.
36+
37+
To easily author, find and understand architectural decisions we adhere to a common format.
38+
39+
### Format Description
40+
Each decision is documented in a separate folder inside [/docs/architecture/decisions](/docs/architecture/decisions) **OR** inside `/<package-name>/docs/architecture/decisions` if the decision is only relevant for that package.
41+
42+
#### Folder Name Format (regex)
43+
```regex
44+
(?<sequencenumber>\d{3})(?<dash>-)(?<shorttitle>.+)
45+
```
46+
47+
Note: The `sequencenumber` is scoped to each package.
48+
49+
#### Folder Structure
50+
```ini
51+
.
52+
├── README.md # The decision document.
53+
└── assets # Optional. Referenced images / assets go here.
54+
```
55+
56+
#### Document Structure
57+
The general structure for each decision document is based on our [ADR Template](./assets/TEMPLATE.md).
58+
59+
## Decision Drivers
60+
* decision retraceability
61+
* supports contributor onboarding
62+
* consistency
63+
* long term health of the project
64+
* follow proven software design practices
65+
66+
## Considered Options
67+
* Do not document architecture decisions
68+
* Document architecture decisions on GitHub Wiki
69+
* Document architecture decisions in the repository
70+
71+
## More Information
72+
### Prior Discussions
73+
- [docs(all, ui-library): propose ADR format #1090](https://github.com/deven-org/boiler/pull/1090)
74+
75+
76+
### Articles and Resources on ADRs
77+
- [Architecture decision record (ADR) examples for software planning, IT leadership, and template documentation](https://github.com/joelparkerhenderson/architecture-decision-record)
78+
- [Has Your Architectural Decision Record Lost Its Purpose?](https://www.infoq.com/articles/architectural-decision-record-purpose)

‎docs/architecture/decisions/000-documenting-architecture-decisions/assets/TEMPLATE.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# {short title of solved problem and solution}
2+
3+
<!-- These are optional elements. Feel free to remove any of them. -->
4+
* **Status:** {proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)}
5+
* **Date:** {YYYY-MM-DD when the decision was last updated}
6+
* **Deciders:** {@github-user-1, @github-user-2, …} <!-- list everyone involved in the decision -->
7+
* **Consulted:** {@github-user-1, @github-user-2, …} <!-- list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication -->
8+
* **Informed:** {@github-user-1, @github-user-2, …} <!-- list everyone who is kept up-to-date on progress; and with whom there is a one-way communication -->
9+
10+
## Context and Problem Statement
11+
{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story.
12+
You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}
13+
14+
## Decision Outcome
15+
16+
> **📍 {title of chosen option}**
17+
18+
{justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
19+
20+
<!-- This is an optional element. Feel free to remove. -->
21+
## Decision Drivers
22+
* {decision driver 1, e.g., a force, facing concern, …}
23+
* {decision driver 2, e.g., a force, facing concern, …}
24+
* … <!-- numbers of drivers can vary -->
25+
26+
## Considered Options
27+
* {title of option 1}
28+
* {title of option 2}
29+
* {title of option 3}
30+
* … <!-- numbers of options can vary -->
31+
32+
<!-- This is an optional element. Feel free to remove. -->
33+
### Consequences
34+
* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
35+
* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
36+
* … <!-- numbers of consequences can vary -->
37+
38+
<!-- This is an optional element. Feel free to remove. -->
39+
### Confirmation
40+
{Describe how the implementation of/compliance with the ADR is confirmed. E.g., by a review or a eslint rule.}
41+
42+
<!-- This is an optional element. Feel free to remove. -->
43+
## Pros and Cons of the Options
44+
### {title of option 1}
45+
<!-- This is an optional element. Feel free to remove. -->
46+
{example | description | pointer to more information | …}
47+
48+
* Good, because {argument a}
49+
* Good, because {argument b}
50+
<!-- use "neutral" if the given argument weights neither for good nor bad -->
51+
* Neutral, because {argument c}
52+
* Bad, because {argument d}
53+
* … <!-- numbers of pros and cons can vary -->
54+
55+
### {title of other option}
56+
{example | description | pointer to more information | …}
57+
58+
* Good, because {argument a}
59+
* Good, because {argument b}
60+
* Neutral, because {argument c}
61+
* Bad, because {argument d}
62+
* …
63+
64+
<!-- This is an optional element. Feel free to remove. -->
65+
## More Information
66+
{You might want to provide additional evidence/confidence for the decision outcome here and/or
67+
document the team agreement on the decision and/or
68+
define when/how this decision the decision should be realized and if/when it should be re-visited.
69+
Links to other decisions and resources might appear here as well.}

‎docs/architecture/decisions/README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Architectural Decisions
2+
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).
3+
4+
# More Information
5+
[000-documenting-architecture-decisions](./000-documenting-architecture-decisions/README.md)

‎packages/ui-library/docs/architecture/decisions/README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Architectural Decisions
2+
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).
3+
4+
# More Information
5+
[000-documenting-architecture-decisions](/docs/architecture/decisions/000-documenting-architecture-decisions/README.md)

0 commit comments

Comments
 (0)