docs(adr): restructure ADRs 010,011,013 to ADR-023 conformance
010/011: relabel Decisions->Decision + add Status/Consequences. 013: add Status + Decision umbrella (existing Consequences untouched). No decision substance changed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
44dbd4628f
commit
b3ca510380
3 changed files with 54 additions and 6 deletions
|
|
@ -1,5 +1,9 @@
|
|||
# ADR-010 — Forgejo integration and CI
|
||||
|
||||
## Status
|
||||
|
||||
Accepted (2026-05-30)
|
||||
|
||||
## Context
|
||||
|
||||
boma's git host, container registry, and (planned) CI all run on a self-hosted
|
||||
|
|
@ -20,7 +24,7 @@ held to the same standard as the rest of the repo's secrets.
|
|||
|
||||
---
|
||||
|
||||
## Decisions
|
||||
## Decision
|
||||
|
||||
### 1. API tokens are managed secrets, least-privilege
|
||||
|
||||
|
|
@ -75,3 +79,21 @@ later if CI load warrants a separate host. Actions is not yet enabled — see ST
|
|||
| Terraform Forgejo HTTP state backend | Forgejo's `/raw/` API is read-only; state can't be written there. Local state instead (ADR-006). |
|
||||
| Admin-scoped automation tokens | Unnecessary privilege; scope to `read:repository` + `read`/`write:package`. |
|
||||
| Ad-hoc UI/API configuration as the norm | Becomes undocumented drift; codify or document instead. |
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
- The planned CI pipeline (see "CI pipeline (planned)") is trunk-based per ADR-003 /
|
||||
ADR-008 — `push to main → lint + Molecule → deploy staging → [manual gate] → deploy
|
||||
production` — running `act_runner` on `ubongo` (or a dedicated runner VM later if CI
|
||||
load warrants); Actions is not yet enabled, so this remains future work tracked in
|
||||
STATUS.md.
|
||||
- Terraform state is not held in Forgejo: its `/raw/` API is read-only and cannot be
|
||||
written, so local state is used instead (ADR-006) (see "What was ruled out").
|
||||
- Automation tokens are scoped to `read:repository` + `read`/`write:package` rather
|
||||
than admin, accepting the limits that least-privilege imposes on what automation can
|
||||
do (see "What was ruled out").
|
||||
- Instance/repo configuration must be codified or documented rather than changed
|
||||
ad-hoc, to avoid the undocumented drift `/review-repo` exists to catch (see "What was
|
||||
ruled out").
|
||||
|
|
|
|||
|
|
@ -1,5 +1,9 @@
|
|||
# ADR-011 — Update and upgrade management
|
||||
|
||||
## Status
|
||||
|
||||
Accepted (2026-06-04)
|
||||
|
||||
**Status: Proposed — draft for discussion (not yet accepted).**
|
||||
|
||||
## Context
|
||||
|
|
@ -10,7 +14,7 @@ drift over time and must be kept current without breaking the homelab: the **hos
|
|||
|
||||
---
|
||||
|
||||
## Decisions
|
||||
## Decision
|
||||
|
||||
### 1. Every service is classified stateful or stateless
|
||||
|
||||
|
|
@ -132,3 +136,19 @@ alert-driven.
|
|||
| 8-weekly as the only stateful path | Too slow for urgent CVEs — hence the DIUN security fast-path. |
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
- A single uniform update policy is rejected: the stateful/stateless split is
|
||||
load-bearing, so stateless services roll on rolling tags while stateful services are
|
||||
pinned `tag@digest`, human-gated, and backup-first (see "What was ruled out").
|
||||
- The weekly run never touches stateful services and the whole fleet is never updated
|
||||
at once, accepting the added orchestration of host ordering and an 8-weekly +
|
||||
fast-path cadence in exchange for bounded blast radius (see "What was ruled out").
|
||||
- No update automation ships until the health-check verification gate is in order; the
|
||||
pipeline is deliberately sequenced behind that harness (see Decision 6).
|
||||
- Several points remain open for discussion (see "Open questions"): where the Proxmox
|
||||
snapshot is driven from across the TF/Ansible boundary; the exact cadences; where the
|
||||
health-check harness lives and the minimum bar that counts as "in order"; whether
|
||||
classification is a per-role `__stateful` flag or a group_vars list; whether the
|
||||
weekly run hits staging first; and the notification + "skip/pause" control channel.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,9 @@
|
|||
# ADR-013 — Heritage: learning from AnsibleBaobabV4 without inheriting it
|
||||
|
||||
## Status
|
||||
|
||||
Accepted (2026-06-04)
|
||||
|
||||
## Context
|
||||
|
||||
boma is the methodology successor to AnsibleBaobabV4 (and V3 before it) — not a new
|
||||
|
|
@ -10,7 +14,9 @@ structure and assumptions creep back in under the guise of "inspiration." This A
|
|||
sets the policy for drawing on V4 without inheriting it. (Resolves the questions
|
||||
previously parked in TODO 3.3 and 10.1.)
|
||||
|
||||
## Principle — translate, don't transplant
|
||||
## Decision
|
||||
|
||||
### Principle — translate, don't transplant
|
||||
|
||||
V4 is **evidence, never authority.** It can show what was needed or what went wrong;
|
||||
it can never be the reason boma does something a certain way.
|
||||
|
|
@ -21,7 +27,7 @@ it can never be the reason boma does something a certain way.
|
|||
- **Acceptance test** for anything V4-derived: *can it be justified purely from
|
||||
boma's principles, with zero reference to V4?* If not, it does not land.
|
||||
|
||||
## What V4 is — and is not — a source of
|
||||
### What V4 is — and is not — a source of
|
||||
|
||||
| Legitimate source of | Never a source of |
|
||||
|---|---|
|
||||
|
|
@ -33,7 +39,7 @@ it can never be the reason boma does something a certain way.
|
|||
Only concrete, verifiable, low-level knowledge crosses over — precisely because it is
|
||||
safe to re-derive, whereas structure and requirements drag assumptions along.
|
||||
|
||||
## Provenance — transient only
|
||||
### Provenance — transient only
|
||||
|
||||
When a boma decision was prompted by a V4 lesson, or a config adapted from V4, the
|
||||
lineage is recorded only in **transient** places: the commit message, the working
|
||||
|
|
@ -42,7 +48,7 @@ extraction warrants one. **Durable artifacts (ADRs, role READMEs, `SECURITY.md`)
|
|||
stand on boma's own terms with no V4 reference.** Honest about lineage in history;
|
||||
clean in the living repo.
|
||||
|
||||
## AI consultation guardrails
|
||||
### AI consultation guardrails
|
||||
|
||||
The AI is the main consumer of V4 — it is on disk and readable. When consulting it:
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue