1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
|
# Using Architecture Decision Records at GeneNetwork
* author: bonfacem
* reviewed-by: fredm, jnduli
> 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.
> -- Michael Nygard
When building or maintaining software, there's often moments when we ask, "What were they thinking?" This happens when we are trying to figure out why something was done a certain way, leading to speculation, humor, or criticism[0]. Given the constraints we face when writing code, it's important to make sure that important decisions are well-documented and transparent. Architecture Decision Records (ADRs) are one such tool. They provide a structured way to capture the reasoning behind key decisions.
ADRs consist 4 key sections [0]:
* Status: An ADR begins with a proposed status. After discussions, it will be accepted or rejected. It is also possible for a decision to be superseded by a newer ADR later on.
* Context: The context section outlines the situation or problem, providing the background and constraints relevant to the decision. This section is meant to frame the issue concisely, not as a lengthy blog post or detailed explanation.
* Decision: This section clearly defines the chosen approach and the specific actions that will be taken to address the issue.
* Consequences: This part lays out the impact or outcomes of the decision, detailing the expected results and potential trade-offs.
Optionally, when an ADR is rejected, you can add a section:
* Rejection Rationale: Briefly provides some context for why the ADR was rejected.
At GeneNetwork, we manage ADRs within our issue tracker, organizing them under the path "/topics/ADR/<project-name>/XXX-name.gmi". The "XXX" represents a three-digit number, allowing for an easy, chronological order of the proposals as they are created.
Here is a template for a typical ADR in Genenetwork:
```
# [<project>/ADR-<XXX>] Title
* author: author-name
* status: proposed
* reviewed-by: A, B, C
## Context
Some context.
## Decision
Decisions.
## Consequences
Consequences.
```
Here are some examples of Genenetwork specific ADRs:
=> https://issues.genenetwork.org/topics/ADR/gn3/000-add-test-cases-for-rdf [gn3/ADR-000] Add RDF Test Case
=> https://issues.genenetwork.org/topics/ADR/gn3/000-remove-stace-traces-in-gn3-error-response [gn3/ADR-001] Remove Stack Traces in GN3
### References
=> https://www.oreilly.com/library/view/mastering-api-architecture/9781492090625/ [0] Gough, J., Bryant, D., & Auburn, M. (2022). Mastering API Architecture: Design, Operate, and Evolve API-based Systems. O'Reilly Media, Incorporated.
=> https://adr.github.io/ [1] Architectural Decision Records. Homepage of the ADR GitHub organization
=> https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html [2] Amazon's ADR process
=> https://cloud.google.com/architecture/architecture-decision-records [3] Google Cloud Center Architecture Decision Records Overview
|
