-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(all, ui-library): propose ADR format
- Loading branch information
Showing
5 changed files
with
162 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
78 changes: 78 additions & 0 deletions
78
docs/architecture/decisions/000-documenting-architecture-decisions/README.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| # 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 `/<package-name>/docs/architecture/decisions` if the decision is only relevant for that package. | ||
|
|
||
| #### Folder Name Format (regex) | ||
| ```regex | ||
| (?<sequencenumber>\d{3})(?<dash>-)(?<shorttitle>.+) | ||
| ``` | ||
|
|
||
| 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 | ||
| ### Prior Discussions | ||
| - [docs(all, ui-library): propose ADR format #1090](https://github.com/deven-org/boiler/pull/1090) | ||
|
|
||
|
|
||
| ### Articles and Resources on ADRs | ||
| - [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) |
69 changes: 69 additions & 0 deletions
69
...rchitecture/decisions/000-documenting-architecture-decisions/assets/TEMPLATE.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| # {short title of solved problem and solution} | ||
|
|
||
| <!-- 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:** {@github-user-1, @github-user-2, …} <!-- list everyone involved in the decision --> | ||
| * **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 --> | ||
| * **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 --> | ||
|
|
||
| ## 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)}. | ||
|
|
||
| <!-- This is an optional element. Feel free to remove. --> | ||
| ## Decision Drivers | ||
| * {decision driver 1, e.g., a force, facing concern, …} | ||
| * {decision driver 2, e.g., a force, facing concern, …} | ||
| * … <!-- numbers of drivers can vary --> | ||
|
|
||
| ## Considered Options | ||
| * {title of option 1} | ||
| * {title of option 2} | ||
| * {title of option 3} | ||
| * … <!-- numbers of options can vary --> | ||
|
|
||
| <!-- This is an optional element. Feel free to remove. --> | ||
| ### 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, …} | ||
| * … <!-- numbers of consequences can vary --> | ||
|
|
||
| <!-- This is an optional element. Feel free to remove. --> | ||
| ### Confirmation | ||
| {Describe how the implementation of/compliance with the ADR is confirmed. E.g., by a review or a eslint rule.} | ||
|
|
||
| <!-- This is an optional element. Feel free to remove. --> | ||
| ## Pros and Cons of the Options | ||
| ### {title of option 1} | ||
| <!-- This is an optional element. Feel free to remove. --> | ||
| {example | description | pointer to more information | …} | ||
|
|
||
| * Good, because {argument a} | ||
| * Good, because {argument b} | ||
| <!-- use "neutral" if the given argument weights neither for good nor bad --> | ||
| * Neutral, because {argument c} | ||
| * Bad, because {argument d} | ||
| * … <!-- numbers of pros and cons can vary --> | ||
|
|
||
| ### {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} | ||
| * … | ||
|
|
||
| <!-- This is an optional element. Feel free to remove. --> | ||
| ## 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.} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |