Release and support policy: what a version promises, which lines get fixes, and how images and npm map onto it #1870

@gdevenyi @thomasbeaudry: this follows up on #1822 and my comment there about a hybrid approach. I worked through a full release and support policy. Before #1822 gets reworked to match it, I'd like your thoughts, especially on anything you would push back on and on the two open questions at the end.

Why

• Every merge to main still re-pushes latest and 2.5.2. The most recent was today, in run 42063797447. main is 564 commits past v2.5.2 (48 feat, 101 fix). A deployment on either tag runs main from whenever it last pulled, and the actual v2.5.2 code is no longer published under any image tag.
• SECURITY.md promises security updates for "the most recent version" only.
• Major numbers have marked big features, not compatibility breaks. The 2.0.0 changelog calls it "a non-breaking upgrade."
• The deployment guide has deployers git clone main, so the compose file they run is unreleased code.

Proposal

1. What a version number promises

A change that breaks any of these is a new major:

1. Stored data. An upgrade boots against the existing MongoDB and object storage and reads every existing record, with no manual step.
2. Deployment config. This covers .env variables, compose services, volumes and ports. A new variable needs a default that keeps the old behaviour. Renaming or removing a variable, or making it required, is breaking. It follows that the newest image of a major works with the compose file from any earlier release of that major.
3. Stored instruments. Every bundle already in a database keeps rendering, and its records keep exporting.
4. The documented HTTP API (spec.json). Additions are fine; removing or changing anything is breaking.
5. Export formats. Column and field names.
6. Access. An upgrade never widens or narrows what an existing user can see or do, unless an admin acts.
7. The public API and CLI of each published npm package.

Outside the contract: UI layout and workflows, undocumented endpoints, internal workspaces, and the gateway↔api protocol. The gateway and api must run the same version.

2. Which lines are supported

• The current major is supported in its newest minor only. To get a fix, upgrade to the newest minor, which §1 makes safe.
• Every superseded major keeps its last minor supported for 36 months after the next major ships.
• The policy applies going forward only. 1.x is not covered.

3. What each line gets

• Security means either of two things.

  • A vulnerability that lets someone, in a documented deployment configuration (the compose stack and its documented options, opt-in ones included), do any of these:
    1. read data they aren't authorized to see;
    2. create, change or delete data they aren't authorized to;
    3. act as another user or gain permissions they weren't given;
    4. run code on the server or in another user's browser.
  • Or a Critical-rated CVE in anything a deployment runs: the base image, OS packages, the runtime npm dependencies of api, gateway and web, and the third-party images the compose stack pins (MongoDB, RustFS, Caddy).

  A CVSS score alone qualifies nothing, and availability-only issues (DoS, resource exhaustion, crashes) never get a backport. They're fixed on the current line in its next ordinary release.

• Data integrity means a bug that silently loses, corrupts or misattributes recorded data, or exports it wrong.

• Critical bug means the stack fails to start, or a core workflow is unusable with no workaround. The core workflows are administering an instrument, collecting a remote assignment, managing subjects and users, and exporting data.

• Maintainers judge reachability and whether a workaround exists. The backport PR states which category it falls under.

• If a fix can't be backported without breaking the line (for example, the fix exists only in the dependency's next major), we publish an advisory saying the line is affected and recommending an upgrade, rather than skipping it quietly.

4. Image tags

• <major>.<minor> is dropped. Under §2 it would stop getting fixes the day the next minor ships, and nothing would tell the people tracking it.
• .env.template defaults RELEASE_CHANNEL to the current major. increment-version.ts rewrites it on a major bump.
• Staging tracks <major>, so it runs what production will run.

5. Which compose file a deployment runs

• Deploy from a release tag, never from main. Install with git clone --branch v<version>, and upgrade with git fetch --tags && git checkout v<newer>. mongo/, rustfs/, sqlite/ and .env are git-ignored, so switching refs never touches data or config.
• A per-major branch that deployers can git pull would be safer, but CI would need to push to a protected branch with a token we don't hold today. That's a later improvement if people keep pulling main.

6. npm packages

• The version numbers stay in lockstep with the platform, but npm publishes only from main. That makes every npm publish a latest publish.
• A release from a branch ships images and a GitHub release, and logs that it is skipping npm. Authors targeting an older major install @^<major>.
• The release environment stays main only, so the npm trusted publisher never has to trust a branch.

7. Breaking changes

• Every breaking change is marked !, with a BREAKING CHANGE: footer written for deployers that says what they have to do. The footer becomes the changelog entry, so a major's upgrade notes come from the commits themselves.
• Merging a ! commit to main is the decision that the next release from main is a major. There is no cadence cap, and main doesn't have to stay releasable as a minor.
• increment-version.ts refuses a bump lower than the recommended one once a breaking commit is in range, and refuses any ! commit on a release branch.
• Automatic detection is follow-up work, with an issue for each check:
  • an OpenAPI diff against the last tag;
  • an .env.template and compose diff against the last tag;
  • export-format snapshots;
  • an upgrade test that boots the previous release's data with the new images.

Out of scope: release cadence and gating. Releases stay at my discretion, as now.

What this means right now

• No release/2.5 branch and no 2.5.3. Under §2, 2.5 isn't a separate line, and a branch cut from v2.5.2 would rebuild code almost no deployment runs.
• Once ci: release from release branches and keep latest on tagged releases #1822 has landed, the next release is cut from main.
  • Before bumping, audit the commits since v2.5.2 against §1. A first pass over .env.template, compose and the Prisma schema found nothing breaking: BIND_ADDRESS has a default, PROJECT_ROOT left the template, and the schema only gained optional fields and new models. The HTTP API, export formats and access are still unchecked. Permission sets need the closest look.
  • If nothing is breaking: release 2.6.0. Its notes tell deployers to set RELEASE_CHANNEL=2 and check out v2.6.0.
  • If something is breaking: release 3.0.0, with upgrade notes. 2.x then gets no maintenance line, because every 2.x image tag points at moving code and there is no stable 2.x build to support. The policy would start with 3.x.
• Confirm the Node version in the build log before announcing the CVE fix. main builds FROM node:lts-krypton, which should already resolve to 24.22.1.

What changes in #1822

These would land as separate small PRs, independent of the workflow:

• increment-version.ts: refuse a lower bump, refuse ! commits on a release branch, and rewrite RELEASE_CHANNEL on a major bump.
• .env.template defaulting to RELEASE_CHANNEL=2, and the deployment guide switching to deploying from a tag.
• A user-facing versioning and support page, and SECURITY.md.
• The detection issues listed in §7.

Open questions

1. How should this land? I'd revise ci: release from release branches and keep latest on tagged releases #1822 in place with the table above, then merge it before the next release. Merging as-is would add a dist-tag scheme, a reconciliation script and environment instructions that this proposal then deletes. The cost is that latest keeps moving with every merge until the revision lands. The alternative is to merge ci: release from release branches and keep latest on tagged releases #1822 now and do the table as a follow-up. That's safe only if the follow-up lands before the next release, because until a release happens the merge run only pushes edge.
2. Where do deployers read the policy? Not discussed yet. Options are a docs page with a table of end-of-life dates, the "Supported Versions" section of SECURITY.md, and whether advisories go through GitHub Security Advisories.