reasampler/docs/product/versioning-and-release.md

# Versioning & release — product notes

Framing behind two release-milestone (M11-adjacent) capabilities Daniel wants made
concrete and decidable:

1. **A release version scheme** — so a "real" stable build can be deployed and
   identified.
2. **A beta side-channel** — so development can continue and a beta build run
   *alongside* the stable one without the beta clobbering the release.

This doc holds the *why*, the forks, and a recommendation. When Daniel picks, the
tickable points land in `PLAN.md` and the deploy/build wiring hands off to dev-ops.
This is a framing note; it changes no source or CMake.

Status: framed by product-designer (2026-07-26). **Forks V1–V4 open — awaiting
Daniel.** Nothing here is settled.

---

## The one constraint that shapes everything: REAPER's startup dlopen

REAPER, at startup only, scans `UserPlugins/` and `dlopen()`s **every** file
matching `reaper_*.dll|dylib|so`, then calls each one's `ReaperPluginEntry`
(CLAUDE.md §REAPER extension contract). Three consequences drive every decision
below:

- **Two matching files load simultaneously.** If both `reaper_reasampler.dll` and
  `reaper_reasampler_beta.dll` sit in `UserPlugins/`, REAPER loads *both* — two
  independent extension instances in one REAPER process. This is the mechanism a
  beta side-channel would exploit, and also its central hazard.
- **No hot reload.** Deploy = copy the binary in, restart REAPER. Any scheme is
  "restart to pick up," never live-swap.
- **Everything is process-global inside REAPER.** Two coexisting instances share
  one REAPER, one Actions list, one project, one ext-state store. Anything keyed by
  a global string (command ids, ext-state namespace, docked-window identity) is a
  potential collision surface between the two.

Two sharp edges follow directly and recur throughout this note:

- **The `STABLE_FOREVER_STRING` command-id contract** (CLAUDE.md; `main.cpp:41`,
  prefix `CEREBELLUM_REASAMPLER_`). Command-id strings are minted once and **never
  changed after shipping** — user keybindings key off them. Two coexisting binaries
  that register the *same* id strings collide in REAPER's Actions list.
- **The `"reasampler"` project ext-state namespace** (shared by the `banks`,
  `view_state`, `project_guid`, `tail_setting` keys, plus the retired `bank_index`).
  Both binaries reading/writing the same namespace on the same open project means a
  **beta can read — and rewrite — a stable project's saved bank/view state.** Given
  the forward-only migrations already in the design (legacy `bank_index` retired
  after promotion; `banks` authoritative thereafter — CONTEXT.md §Multi-bank), a
  beta that writes a newer schema into a project a user then reopens in stable is a
  real corruption path, not a theoretical one.

Everything below is really about how much of that global surface a beta channel is
allowed to touch.

---

# Part 1 — Version scheme + where the version lives

## What we have today

- No version anywhere. `CMakeLists.txt:2` is `project(reaper_reasampler LANGUAGES
  CXX)` — no `VERSION`. The binary announces itself only as `"ReaSampler loaded.\n"`
  to the console (`main.cpp:960`). There is no number a user, a bug report, or a
  future migration can key off.
- The natural user-visible readout already exists: the docked LICE bank panel, and
  the console (`ShowConsoleMsg`). A version has cheap homes; none is wired.

## The number itself (V1) — recommendation: **semver, sourced from CMake**

Recommend **semantic versioning** (`MAJOR.MINOR.PATCH`) with the number's single
source of truth in `CMakeLists.txt` via `project(reaper_reasampler VERSION x.y.z)`,
threaded into the binary as a compile definition and surfaced to the user.

Semver fits because ReaSampler already has the two events semver exists to signal,
and they matter here specifically:

- **MAJOR / MINOR** track user-visible capability (a new pillar landing: Phase R
  prune, M9 slots).
- **PATCH** tracks fixes.
- Most importantly, ReaSampler carries **persisted, migrating project state** (the
  `"reasampler"` ext-state, forward-only migrations). A version stamped *into the
  saved blob* is what lets a future build say "this project was written by 1.4, I am
  1.6, run the 1.4→1.6 migration" — or refuse gracefully. That is a concrete,
  already-latent need, not ceremony. **Recommend stamping the writing version into
  the ext-state blob** as part of whichever release wave ships (small addition to
  the persist section; a sibling `schema`/`app_version` field).

**Source of truth: CMake `project(VERSION)`.** One number, in the build system,
flowed outward — never hand-edited in a header. `project(... VERSION x.y.z)`
populates `PROJECT_VERSION` / `PROJECT_VERSION_MAJOR|MINOR|PATCH`, which a
`target_compile_definitions` (e.g. `REASAMPLER_VERSION="…"`) threads into the
binary. This is the standard CMake idiom and keeps the tag, the binary, and any
about-string in lockstep from one edit.

**Alternatives considered:**

- **Git-derived version (`git describe --tags`)** baked at configure time. Pro: the
  build literally cannot disagree with the tag; encodes commits-since-tag + dirty
  state, which is *excellent for a beta* ("1.4.0-beta.3+7.gab12cd"). Con: needs git
  present at build and a tag discipline; a source tarball without `.git` builds
  "unknown." **Recommendation: use it for the beta channel's suffix, not as the base
  number.** Best of both: `project(VERSION)` owns the release triple; `git describe`
  decorates beta builds. (See V2.)
- **A hand-maintained `version.h`.** Rejected — a second source of truth that drifts
  from the tag. The whole point of one source is that release can't ship a binary
  that lies about its number.
- **Date-based / CalVer (`2026.07`).** Coherent, but ReaSampler's changes are
  capability-shaped (pillars landing), not time-shaped, and CalVer says nothing
  about migration compatibility, which is the load-bearing use here. Semver earns
  its place; CalVer doesn't.

## Where the user sees it (V3) — recommendation: **panel readout + startup log, defer an about box**

Three candidate homes, cheap to expensive:

1. **Startup console line** — upgrade `"ReaSampler loaded.\n"` to `"ReaSampler
   x.y.z loaded.\n"`. Nearly free, and it lands the version in exactly the place a
   user copies from when filing a bug. **Do this regardless of the other choices.**
2. **Bank-panel readout** — a small version string in the docked LICE panel
   (header corner or footer, near the existing tail toggle / mode switch). Always
   visible, no new window, matches the LICE-drawn house style. **Recommend this as
   the primary user-facing home.**
3. **An "about" action / dialog** — a bindable `ReaSampler: about` that pops
   version + build channel + build hash. More than the moment needs; a SWELL dialog
   is real surface to maintain. **Defer** — the panel readout + console line cover
   the actual need (identify the running build). Pick this up only if a beta channel
   makes "which build am I running" a frequent question.

Recommendation: **(1) + (2) now, (3) deferred.** The version wants to be visible
*passively* (panel) and *copyably* (console), and a beta channel makes the panel
readout do double duty as the channel indicator (Part 2).

**Open decision V3 for Daniel:** panel placement — header corner vs. footer strip
vs. folded into the existing mode-switch/tail-toggle chrome. This is a small panel
polish call, same class as the settled "active-bank indicator placement" residual.

---

# Part 2 — Beta side-channel

The goal: keep shipping a stable build users depend on, while running a beta of
in-progress work **alongside** it, so the beta can be exercised in real projects
without the beta's newer/rougher state clobbering the stable install or stable
projects.

The design axis is **coexistence**: must stable and beta load into the *same REAPER
at the same time* (true side-by-side), or is it enough to run *one at a time* with
clean, safe switching? That axis splits the options.

## Option A — Separate binary name, both load simultaneously (true coexistence)

Ship `reaper_reasampler_beta.dll` next to `reaper_reasampler.dll`. REAPER loads
both; the user has a stable ReaSampler and a beta ReaSampler live in one session.

This is the most powerful shape — and the most dangerous, because of the three
global-collision surfaces the startup-dlopen constraint creates. **A separate
binary name alone does not isolate them; it just makes them coexist.** For Option A
to be safe, *three* things must diverge in lockstep, not just the filename:

1. **Command-id strings must diverge.** Both binaries register actions; if the beta
   mints `CEREBELLUM_REASAMPLER_CAPTURE_TRACK` too, REAPER's Actions list has two
   entries claiming one id — collision, and the `STABLE_FOREVER_STRING` contract is
   violated. The beta needs its **own prefix** (e.g. `CEREBELLUM_REASAMPLER_BETA_`).
   Sharp edge: that means the beta's ids are a *distinct forever-family* — a user's
   beta keybindings won't carry to stable, and vice versa. That is arguably correct
   (they're different installs), but it must be a deliberate decision, because once
   the beta ships those beta ids are *also* forever-stable. **You are minting a
   second permanent id namespace, not a throwaway.**

2. **The ext-state namespace must diverge — or the beta corrupts stable projects.**
   This is the severe one. If the beta writes `banks`/`view_state` under
   `"reasampler"`, a project saved by the beta carries beta-schema state that stable
   then reads (and the forward-only migration may have already retired the key
   stable expected). The beta must write under its **own namespace** (e.g.
   `"reasampler_beta"`). Consequence, and it cuts both ways: a **beta cannot see a
   stable project's bank** (different namespace), so testing the beta against a real
   populated project means the bank looks empty until re-captured. That is the price
   of isolation, and it is the *right* price — a beta that shares stable's namespace
   is a data-loss bug waiting to happen. **This divergence is non-negotiable if
   Option A is chosen.**

3. **The docked-window / docker identity should diverge**, so the two panels are
   distinguishable and don't fight over one dock slot. Lower-severity (a UX
   annoyance, not corruption), but part of the same "everything global must fork"
   picture.

Net: Option A delivers genuine side-by-side at the cost of forking *every global
identity the extension owns*. It is a **compile-time-parameterized second product**,
not a branch artifact — which points straight at Option C as the *mechanism* for how
you'd actually build it.

## Option B — One binary, branch discipline, one installed at a time

`dev` → beta builds, `main` → release builds; the version string carries a
`-beta`/`-dev` suffix so the running build self-identifies; **only one is installed
at a time.** No coexistence — you swap the binary and restart REAPER to change
channels.

- **Pro:** *zero* collision surface. Same command ids, same ext-state namespace, one
  file — because only one is ever loaded. Nothing forks. Simplest by a wide margin.
- **Pro:** matches the repo's existing branch reality (`dev` is the working branch,
  `main` the release branch — visible in the current git state).
- **Con:** no true side-by-side. To A/B stable against beta you swap files and
  restart. For a solo developer this is often *entirely fine* — the friction is a
  file copy + restart, not a corruption risk.
- **Sharp edge (the reason it's still not free):** if the beta writes a
  newer/experimental ext-state schema into a real project, then you swap back to
  stable and open that project, **stable reads beta-written state.** One-binary
  branch discipline removes the *simultaneous* collision but not the *sequential*
  one — the project file is the shared surface across a channel swap. Mitigation:
  either (a) keep the beta strictly schema-compatible with stable (no ext-state
  shape changes on the beta channel — often true, since most beta work is behavior,
  not persistence), or (b) accept "don't open beta-touched real projects in stable"
  as a discipline, or (c) stamp the writing version into the blob (V1) so stable can
  at least *detect* and refuse/migrate rather than silently mis-read.

## Option C — Compile-time build flag (the mechanism, usable under A or B)

A CMake/preprocessor switch (`-DREASAMPLER_CHANNEL=beta`) that, in one build tree,
sets: output name, command-id prefix, ext-state namespace, version suffix, and the
panel channel indicator. This is not really a *third* strategy — it's *how you
implement* the divergence Option A demands, or *how you stamp the suffix* Option B
wants. It's the knob; A and B are policies for the knob.

- Under **Option A**, the flag is what forks the two binaries from one source
  cleanly — flip `REASAMPLER_CHANNEL`, get the beta's name/prefix/namespace/suffix
  as a coordinated set, so the three-way divergence can't get out of sync by hand.
- Under **Option B**, the flag just sets the suffix + a channel tag; name/prefix/
  namespace stay shared because only one loads.

The flag is worth having either way because it makes "what makes a beta a beta" a
**single, auditable definition** instead of scattered `#ifdef`s.

## Recommendation: **B now, built on C, with A as the deliberate upgrade later**

Start with **Option B (branch discipline, one at a time) implemented through a
compile-time channel flag (Option C)**:

- Ship the release from `main` as `reaper_reasampler` with a clean semver
  (`x.y.z`).
- Build beta from `dev` through `-DREASAMPLER_CHANNEL=beta`, which stamps a
  `-beta`/`-dev.<git-describe>` **version suffix** and a **panel channel indicator**
  (so a beta is unmistakable at a glance — the version readout from Part 1 doubles as
  the channel badge). This is where `git describe` earns its keep (V2): the beta
  suffix carries commits-since-tag so two betas are distinguishable.
- **Do not fork the command-id prefix or the ext-state namespace yet** — because
  under B only one binary loads, so there is nothing to collide with, and forking
  them prematurely commits you to a second forever-stable id family and splits your
  own test data for no gain.

Then treat **Option A (true coexistence) as a later, deliberate upgrade** if and
only if "swap-and-restart" proves too slow — i.e. you find you genuinely need stable
and beta live in one REAPER to compare them. The upgrade is *clean* precisely
because you built B on the channel flag: flipping A "on" means extending the same
flag to also fork the output name, the command-id prefix (`_BETA_`), and the
ext-state namespace (`"reasampler_beta"`). The seam is designed now; the feature is
deferred (the same *defer-the-feature-design-the-seam* discipline the project
already applies to the owned-file manifest and Phase D adaptability).

Why not A first: A's power is real but it forces you to mint a **second permanent
command-id namespace** and a **second ext-state namespace** on day one — both
irreversible-ish commitments (the ids are forever-stable; the namespace split means
beta and stable never share a project's bank). That is a large, permanent price for
a convenience (simultaneous compare) you may not need. B pays nothing permanent and
keeps A one flag away.

Why not B without the flag: hand-managing the suffix and channel badge across two
branches drifts. The flag makes "beta vs. release" one definition and is the exact
thing you'd extend for A — so building B *through* C costs little now and saves the
A upgrade later.

### The sharp edge that survives every option: ext-state across a channel swap

Whichever way this goes, call out loudly (and this is a genuine **Daniel decision**,
V4): **can a beta build write experimental `"reasampler"` ext-state schema that a
stable build might later read?**

- Under **A** with a forked namespace: no — isolated, safe, at the cost of beta not
  seeing stable's bank.
- Under **B**: yes, sequentially — the project file is shared across a swap. Needs a
  policy: beta stays schema-compatible, **or** the version-stamp-in-blob (V1) lets
  stable detect-and-refuse, **or** "don't open beta-touched real projects in stable"
  is an accepted discipline.

The cheapest robust mitigation across both is **V1's version stamp in the ext-state
blob** — it turns a silent mis-read into a detectable "this project was written by a
newer/other build." Recommend adopting it as part of the first release wave
regardless of the A/B choice, because it's the seam that makes every later channel
and migration decision safe.

---

# Part 3 — Deploy / CD touchpoints (hand-off to dev-ops)

Framing only — the actual pipeline is dev-ops's to author. The strategy above
implies these touchpoints:

- **Tag → version.** Release is cut from a git tag on `main`; `project(VERSION)` is
  bumped to match the tag (or the tag is derived from it — pick one direction and
  keep it one-way). Beta builds from `dev` carry `git describe` in the suffix.
- **Channel is a build parameter.** `-DREASAMPLER_CHANNEL=release|beta` selects the
  suffix/badge now (Option B) and, if Option A is ever turned on, the output
  name/prefix/namespace too. One flag, one definition of "what is a beta."
- **Artifact per platform.** The binary is `reaper_*.dll|.dylib|.so`; the macOS/Linux
  builds need the SWELL resgen step (CLAUDE.md §SWELL dialog resources) baked into
  the pipeline. Three platform artifacts per channel per release.
- **Install is copy-in + restart** (no hot reload). A release "deploy" is publishing
  the artifact for the user to drop into `UserPlugins/`; there is no server-side
  rollout. Any auto-update story is out of scope here and would be its own note.
- **The ext-state version stamp (V1)** is the one piece of forward-compatibility
  plumbing the pipeline should ensure ships in the first versioned release, so every
  subsequent build can reason about older saved state.

---

# Open decisions for Daniel

- **V1 — version scheme.** Recommend semver via `project(VERSION)` as single source
  of truth, **plus a writing-version stamp in the `"reasampler"` ext-state blob** for
  forward migration/detection. Approve scheme + whether the ext-state stamp lands in
  the first release wave.
- **V2 — beta suffix source.** Recommend `git describe` decorating beta builds
  (`x.y.z-beta.N+g<hash>`) while `project(VERSION)` owns the release triple. Approve
  or simplify to a plain `-beta` suffix.
- **V3 — user-visible home + placement.** Recommend startup console line + a
  bank-panel version/channel readout now; about-box deferred. Panel placement
  (header corner / footer / folded into existing chrome) is the residual call.
- **V4 — beta channel shape (the big one).** Recommend **Option B (branch
  discipline, one at a time) built on an Option C compile-time channel flag**, with
  **Option A (true simultaneous coexistence) designed-as-a-seam but deferred**. The
  sub-decision that must be made explicitly either way: **the ext-state-across-a-
  channel-swap policy** — isolate (A), stay schema-compatible / stamp-and-detect (B),
  or accept the discipline. This is genuinely Daniel's call, not one to default.