docs: plan Nix flake packaging (spec, ADR 0018, tasks 0036-0042)
All checks were successful
CI / test (push) Successful in 55s

Add the design record for distributing gitea-axi as a Nix flake: a
package, a development shell, and a checks output, plus the continuous
integration changes that come with it.

ADR 0018 records the wrapper's deference to the operator's own `git` and
`tea` — the reverse of the hermetic instinct, chosen because `tea`
refreshes OAuth tokens in place and so must not have two versions
mutating one credential store.

Also records the `tea`-is-still-a-runtime-dependency gotcha, which ADR
0002's title obscures.
This commit is contained in:
2026-07-19 22:22:02 -04:00
parent 408956cf32
commit 0cbfe43ae0
10 changed files with 459 additions and 0 deletions

View File

@@ -0,0 +1,34 @@
---
spec: nix-flake-packaging
blocked-by: 0036-parameterized-installed-binary-tier
---
## What to build
Continuous integration moves off end-of-life Node, tests the full range of Node versions the package claims to support, and gains the two test tiers it currently never runs.
The workflow matrixes over the two supported Node versions, and the declared engine range in the package manifest narrows to match.
Today the manifest promises support down to Node 20 while testing only Node 20, so the entire claimed range below the tested version is unverified and its floor is end-of-life.
Narrowing is free right now because nothing has been published and no tags exist; that window closes at first publish.
The packaging tier currently asserts that the declared range mentions Node 20, so that assertion changes with it — part of this work rather than a later surprise.
The live end-to-end tier moves to the highest matrix leg only: it exercises the Gitea API contract rather than Node-version behavior, and each leg provisions a full Gitea service.
Two tiers join the workflow.
The benchmark harness tier runs on every leg — it is deterministic, needs no network or agent SDK, and is currently unguarded despite its non-default runner configuration being an easy thing to believe is running when it is not.
The packaging tier runs on the highest leg only, being slow and largely version-independent; it is the only automated guard on the distribution artifact, given that publishing is a manual command.
The benchmark smoke tier stays out: it targets a live host discovered through the maintainer's own credentials and skips cleanly when they are absent, so here it would pass by skipping — a green check that verified nothing.
The workflow keeps its container-and-npm shape and its GitHub Actions compatibility; nothing migrates to building via Nix.
## Acceptance criteria
- [ ] The workflow runs a matrix over the two supported Node versions, and no leg runs an end-of-life Node.
- [ ] The manifest's declared engine range names exactly the versions the matrix tests.
- [ ] The packaging tier's engine assertion matches the narrowed range and passes.
- [ ] The live end-to-end tier runs on the highest leg only.
- [ ] The benchmark harness tier runs on every leg, under its own runner configuration.
- [ ] The packaging tier runs on the highest leg only.
- [ ] The benchmark smoke tier does not run.
- [ ] The workflow syntax stays GitHub-Actions-compatible.