ADR 0107: A stable channel on top of the weekly patch train
Status: Accepted Date: 2026-11-06 (accepted 2026-11-09) Relates: ADR 0033 (rc tags and E2E gates), ADR 0068 (patch content gated by safety), ADR 0071 (stage, verify, promote), ADR 0102 (patches from main), #1557 (release notes opening), #2308
Context
Dexaflow ships a patch a week. ADR 0068 lets a 0.x patch carry features and
migrations when they meet a safety bar, and ADR 0102 cuts every patch from
main. That suits development: a fix reaches users in days, and nothing waits
for a minor.
It does not suit a production operator. A patch a week means a possible
schema change a week, and nothing in a release says which patch has had time
on a running install. Every GA is equally “Latest” on GitHub, so the default
install.sh and a chart pinned to the newest version always take the newest
patch, the one with the least time in use. The project already has the signals
a production operator would want, but they are not attached to a version:
- The soak battery (
test/soak) runs for 48 hours on the maintainer’s hardware; CI only runs its six minute smoke, nightly and on rc tags. - The chaos scenarios (
scripts/chaos) run every week on a k3d runner (chaos-weekly.yaml, #2411). - Regressions are reported as issues, with no label that ties them to the version they appeared in.
The release body states what changed. Since #1557 it opens with Breaking changes and Action required; it still does not say how an operator gets back if the upgrade goes wrong, which is the first question before a production upgrade.
Decision
- The weekly train stays. Every patch is still cut, tagged and published as today (ADR 0033, ADR 0071, ADR 0102). Nothing about its content changes.
- A patch becomes stable when all of these hold:
- it has been published for at least 7 days;
- the workflows of the tag and of the rc it was promoted from are green, including the soak smoke that runs on every rc tag;
- the first weekly chaos run (
chaos-weekly.yaml) on amaincommit that contains the tag passed; - no open issue labeled
regressionnames it (the label is new; an issue gets it when a behavior that worked in an earlier GA broke, and names the first version it broke in). The 48 hour soak (test/soak) is not part of the bar yet: it runs on the maintainer’s hardware, and requiring it every week would make one machine the gate. Until a runner can run it unattended it is optional evidence: when it has run on the tag, the pull request that marks the patch links its verdict file, and a failed soak blocks the mark. Once that runner exists, a passing 48 hour soak on the tag joins the bar (phase 2), by a change to this ADR. A later patch of the same minor that meets the bar replaces it. A patch found to carry a regression after it was marked stable loses the mark, and the previous stable patch is named again until a fixed one qualifies.
- One file records the channel.
.github/stable.txtonmainlists the stable patch of each supported minor, oneX.Y vX.Y.Zline each, changed only by pull request with the evidence above linked in its body. Tags stay immutable (ADR 0033); the mark is the file, not a moving tag. - The defaults point at stable.
install.shgainsDEXAFLOW_CHANNEL=stable|latest, defaultstable, which reads.github/stable.txtfrommain;DEXAFLOW_VERSIONstill pins an exact release.- The chart README, the quickstart and the production profile name the stable patch and say how to follow it.
- The GitHub “Latest” mark stays on the newest patch: it is what GitHub shows on the repository page, and moving it backward would hide new patches from people who want them.
- Every release body states its rollback class, in the opening #1557
added, next to Action required:
- Binary swap: no migration; rolling back is installing the previous version.
- Schema step: migrations with down files that lose nothing; rolling
back is
helm rollbackafter running the down migrations to the previous schema, asoperate/upgrades.mddescribes for that version (Lite has no down command and restores its snapshot instead). - Restore: a migration the previous version cannot run on, or one whose
down loses data; rolling back is restoring the pre-upgrade backup
(
operate/backup-restore.md). The class is the most severe of the release’s changes. A new changelog kind is not needed: the release notes script reads the class from theUpgradeentries, and a release with noUpgradeentry and no new migration is a binary swap. It also gains a Known issues section, from the openregressionissues that name the version.
- The rc and release checks do not change. Stable is a statement made after a release, from evidence gathered after it; it never blocks a cut.
Alternatives
- Fix-only patches, features in minors. A patch would carry only fixes, and features would wait for a minor every few weeks. It is the usual model and the one ADR 0068 replaced: in the 0.5 line almost every patch carried a feature someone was waiting for, and splitting them would mean either slower features or a second branch to pick into, the cost ADR 0102 removed. It makes every patch safer, but it does not tell an operator which one has been run for a week.
- No change until 1.0. Production users take the newest patch and read its notes. Cheapest now, but it leaves every production operator to judge each patch alone, without a signal from the project, for the months until 1.0.
- A moving
stablegit tag or astableimage tag. Simple to consume, but it breaks tag immutability (ADR 0033) and the signed provenance of an image tag. The file keeps every artifact immutable and points at one.
Consequences
- Production users get a default that has run for at least a week, and the weekly train keeps its pace for everyone else.
- The weekly chaos run and the rc soak smoke become release evidence; both already run on GitHub runners, so phase 1 adds no work on the maintainer’s hardware. The 48 hour soak stays optional until a self-hosted runner can run it every week; that runner is the follow-up that starts phase 2.
- The
regressionlabel needs triage discipline: a report has to name the version it first appeared in, or the mark cannot be judged. - A stable patch can be up to two or three weeks behind the newest one, and a
security fix in a newer patch is the exception: a
Securityentry fixing a vulnerability rated Medium or higher makes the stable mark move to that patch once its rc checks pass, without the 7 days.
Open questions
- Who marks a patch stable. Phase 1: the maintainer approves a pull request
that changes
.github/stable.txt, which any contributor can open once the evidence is in. A scheduled workflow that opens it is a later step. - How many minors keep a stable line once 0.6 ships: only the newest, or the newest two while users move.