From 5d3cadbf363acb18fd2415d5bdfab439f2715ab1 Mon Sep 17 00:00:00 2001 From: "M.V. Hutz" Date: Mon, 27 Jul 2026 19:01:17 -0400 Subject: [PATCH] docs: define adr lifecycle --- docs/adr/2026-07-09-adr-lifecycle.md | 128 +++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 docs/adr/2026-07-09-adr-lifecycle.md diff --git a/docs/adr/2026-07-09-adr-lifecycle.md b/docs/adr/2026-07-09-adr-lifecycle.md new file mode 100644 index 0000000..4c76b11 --- /dev/null +++ b/docs/adr/2026-07-09-adr-lifecycle.md @@ -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.