web/architecture
1
0
Fork 0
Code Pull Requests Actions Activity

docs: define adr lifecycle

Browse Source
This commit is contained in:
Maxim Hutz
2026-07-27 19:01:17 -04:00
parent e08bdafbc1
commit 5d3cadbf36
1 changed files with 128 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/adr/2026-07-09-adr-lifecycle.md
+128
View File
@@ -0,0 +1,128 @@
---
title: Define ADR lifecycle.
status: "accepted"
supersedes: null
---
## Context & Problem Statement
One of the main goals of this Gitea instance is to demonstrate my understanding of software design and process.
ADRs are a major contributor to achieving this, because they hold my thought process when designing software.
This carries to my most complex project so far: the Gitea instance itself.
Along with their importance, these ADRs can also be sensitive.
They may describe my software's weaknesses, as well as intimate topology.
I do not want to give potential attackers the 'keys to the kingdom'.
This problem has two sides to it:
> How can I demonstrate my understanding of cloud architecture with ADRs,
> while keeping that architecture safe from exploitation?
No matter how I publish them, the ADRs need to be written and stored somewhere.
Where should they go?
### Scope
- I assume that the server which hosts ADRs cannot be compromised, unless by the content of ADRs.
- By publishing, I mean creating a new file in a public repository, which contains just the contents of some private ADR.
Publishing does not copy history of it, or other files.
## Decision Drivers
- **Visibility**:
I want to publish my ADRs so that others can see.
- **Security**:
I want to protect sensitive information about my cloud architecture.
Publicly disclosing current, architectural weakness would threaten this instance.
For this ADR, anything that (1) discloses a current security weakness or (2) has reconnaissance value is considered 'sensitive'.
Sensitivity is a spectrum: some things are more sensitive than others.
- **Honesty**:
I want the ADRs to display my decision, as it was decided.
## Considered Options
1. **Publish all ADRs to a public repository.**
- **Security**:
Catastrophic loss of security, if a published ADR contains information about a current weakness.
It is irreversible, which exposes the system to attack.
- **Visibility**:
Perfect visibility: no ADR is unpublished.
- **Honesty**:
Potential loss of honesty.
If visibility is paramount, then an honest, sensitive ADR is a security breach.
To compensate, this option might sacrifice honesty.
2. **Publish all ADRs to a private repository.**
- **Security**:
Perfect security, regardless of content sensitivity.
- **Visibility**:
Absolute loss of visibility, as no ADRs are ever published.
- **Honesty**:
Perfect honesty, because there is no threat to security.
3. **Save original ADRs privately; publish redacted versions to public repository.**
- **Security**:
Strong security for sensitive ADRs.
Not perfect though, as redaction is manual, and may introduce error.
- **Visibility**:
Substantial loss of visibility for sensitive ADRs.
The value in visible ADRs comes from the detail of the options considered.
By redacting sensitive criteria for the decision, those options become vague.
- **Honesty**:
Loss of honesty for sensitive ADRs.
If I based an ADR off a current weakness, then a modified copy misrepresents the decision.
4. **Only publish ADRs classified as 'non-sensitive' to a public repository.**
- **Security**:
Strong security: only non-sensitive ADRs live in public.
It is not perfect, because classification is a manual process.
- **Visibility**:
Absolute loss of visibility for sensitive ADRs.
They are only as sensitive as their decision is and its context.
Even if either change (i.e. the ADR is superseded, or a sensitive vulnerability is fixed), the ADR is not published.
And, if it is referenced by future ADRs, they will also be withheld indefinitely, too.
- **Honesty**:
Perfect honesty.
No documents are modified.
5. **Accept ADRs in a private repository; publish on a release condition.**
- **Security**:
Strong security: ADRs are published only when their visibility outweighs their security implications.
It is not perfect, because the release condition may assume some security risk.
- **Visibility**:
Loss in visibility for ADRs waiting in the private repository.
ADRs may pile up in the private repository if I file them faster than I can act on.
And, if there is an ADR I will never publish, then any future decisions tied to it cannot either.
- **Honesty**:
Perfect honesty.
No documents are modified.
## Decision Outcome
I chose option 5.
Its conditional trigger for publishing allows me to fine-tune security vs. visibility, while keeping honesty intact.
- **Good**:
No ADR is misrepresented. While the release condition is unmet, it will not be published.
- **Good**:
No ADR is withheld unless it does not meet the release condition.
- **Bad**:
If ADRs are accepted faster than I can hit release conditions, then they'll pile up in the private repository.
I accept the risk of pile-up as part of this decision.
- **Bad**:
If an ADR can never be published, then any tied to it cannot either.
### Consequences
- A private repository will be created to hold the new ADRs.
- A public repository will be created to hold the new published ADRs.
- Each ADR will contain a release condition, accepted along with the ADR.
When the release condition is met, the ADR must be published.
### Release Condition
No weaknesses.
Publish immediately.