docs: define adr lifecycle

2026-07-27 19:01:17 -04:00
parent e08bdafbc1
commit 5d3cadbf36
1 changed files with 128 additions and 0 deletions
@@ -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.