Calendar versioning + dual-pace edge/stable channels (ADR-0004) — feedback welcome

[ChrisonSimtian]

TL;DR

Fallout is adopting calendar versioning + a dual-pace channel model, now captured in ADR-0004 (landed in #301). This thread is the place to react, push back, and shape the rollout. 🙏

Why

Our contributor velocity is bimodal. Some of us work AI-assisted and ship a lot per week; others hand-write and move deliberately. Left unstructured, those two tempos collide — either the fast lane destabilises what everyone depends on, or the slow lane becomes a gate the fast lane waits behind. We want both paces, neither blocking the other.

The model (short version)

• Calendar versioning YYYY.MINOR.PATCH — it's mechanically valid SemVer (the major just is the year), so tooling/ordering are unchanged. Breaking changes batch to the yearly major cut; mid-year stable is strictly non-breaking. A year simply ships more.
• main is the edge channel — fast/AI lane, intentionally unstable, daily date-stamped prereleases to GitHub Packages only.
• release/YYYY = the stable train — hardened deliberately, non-breaking minors/patches only. This is the deliberate-cadence crowd's domain, with rigorous, unhurried review — there's no clock on it, because edge already served the impatient.
• [Experimental("FALLOUT0xx")] marks opt-in unstable APIs that can ride any channel — so "experimental" doesn't require a divergent fork. Promoting to stable = deleting the attribute.
• Legacy release/v10 keeps its 10.x line for security/critical fixes — v10 consumers do nothing. release/v11 is retired (nothing clean shipped under it).

The point is as much social as technical: the fast lane never blocks on slow review, and the slow lane is never steamrolled — the thing they guard (stable) is theirs to pace.

On gitflow + semver

@dennisdoomen — your gitflow + semver suggestion drove a lot of this. The model deliberately keeps semver mechanics (CalVer is valid semver; breaking-batched-to-year keeps "major = breaking" honest) and keeps stable insulated from in-flight churn — but implements that insulation with short-lived release/YYYY trains cut from trunk rather than a permanent develop branch, to avoid long-lived divergence. Would love your read on whether that captures the intent, and where it doesn't.

What I'd like feedback on

1. CalVer shape — YYYY.MINOR.PATCH with breaking batched to the year cut. Reasonable? Any tooling concerns?
2. Edge from main to GitHub Packages — does intentionally-unstable-on-main land right, or would you prefer a separate branch?
3. [Experimental] discipline — comfortable relying on the analyzer-enforced attribute for opt-in surface?
4. Review tiers — light on edge, rigorous on the stable train. Does that match how you'd want to spend review time?

Nothing here is set in stone — the ADR is the starting point, not the last word. The follow-up PRs (version.json → CalVer, release.yml edge job, the [Experimental] convention) will land incrementally, and a roadmap board is going up so the stable/preview work is visible.

Full detail: ADR-0004 · branching runbook · agent reference

[dennisdoomen]

Our contributor velocity is bimodal. Some of us work AI-assisted and ship a lot per week; others hand-write and move deliberately.

I do use AI a lot, but don't have infinite tokens, nor infinite time, and I still move deliberately ;-)

CalVer shape — YYYY.MINOR.PATCH with breaking batched to the year cut. Reasonable? Any tooling concerns?

Nope. Sounds like a fine approach. A single breaking release per year as a default won't hurt anybody

Edge from main to GitHub Packages — does intentionally-unstable-on-main land right, or would you prefer a separate branch?

Based on the principle-of-least-surprise, I would expect main to be the stable version that lands stable improvements and bug fixes. develop would be the one that contains those fast and potentially breaking changes. If the changes are non-breaking, you can still merge those to main (through a release branch for stabilization if necessary).

[Experimental] discipline — comfortable relying on the analyzer-enforced attribute for opt-in surface?

Nice. Didn't know about that one, but I'm fine with that.

Legacy release/v10 keeps its 10.x line for security/critical fixes — v10 consumers do nothing. release/v11 is retired (nothing clean shipped under it).

Assuming you want to follow a well-known branching strategy like GitFlow, I would call this support/v10

Review tiers — light on edge, rigorous on the stable train. Does that match how you'd want to spend review time?

Kind of. But if you keep going as fast as you're going right now, you will be the only one understanding what's happening there. So requesting reviews or feedback on those PRs will benefit all of us.