Source builds report a version instead of "dev"

[tbcsec]

What & why

The update check (#111) had source builds reporting dev. The README's headline quickstart is git clone + docker compose up --build, so that's most deployments — the adoption data would have been one opaque bucket with no version granularity at all.

Worse: dev doesn't parse, so is_newer() always returned False and a source build could never be told a new release existed. The majority of users would silently never see an update notice. That's arguably the bigger loss of the two.

The default is now the base release plus a marker — 1.2.0-src.

Why the marker, rather than a bare 1.2.0

It's true. A clone of main genuinely isn't the release — main starts accumulating the next version's work the moment a tag is cut. 1.2.0-src says "a source tree based on 1.2.0", which is accurate; a bare 1.2.0 would not be.

It keeps information that's otherwise thrown away. 1.2.0: 40 / 1.2.0-src: 120 tells you where to invest in packaging and docs; a merged 1.2.0: 160 doesn't. Splitting is trivially reversible in a query; merging loses it permanently.

It costs nothing mechanically. The suffix is already accepted by both the client regex and the endpoint's, parses to (1, 2, 0) for ordering, and stores as its own row. Verified on both sides:

• is_newer("1.3.0", "1.2.0-src") → True — a source build gets told about 1.3.0
• is_newer("1.2.0", "1.2.0-src") → False — no spurious notice at parity

The weakness this introduces, and the guard for it

A hand-maintained default fails silently. Forget the bump and every source deployment reports the previous release for as long as it takes someone to notice the numbers look wrong.

So release-images.yml gains a version-check job that build now needs. It refuses to publish images if:

• the default doesn't match the tag, or
• the -src marker has been dropped — a well-meaning tidy-up would otherwise silently merge source builds into the image bucket.

Verified by simulation: v1.2.0 → allowed, v1.3.0 → blocked. YAML parse and job wiring checked too, since a syntax error there would only surface at release time.

Documentation

There was no documented release process at all, so the bump would have been folklore. CONTRIBUTING.md gains a "Cutting a release (maintainers)" section: bump the default, tag, write the notes — with the reasoning for why step 1 matters and what to do if the guard fires.

Comments the change made wrong

Also corrected — frontend/src/lib/types.ts described dev as the source-build value. dev itself is still handled, for a deployment that sets APP_VERSION=dev explicitly, so its test case stays with an adjusted comment.

The endpoint side is a separate commit in the flagpost-website repo (45202ef): its README's "how many are running from source" query filtered on version = 'dev' and would now return nothing — anyone running it would reasonably conclude nobody builds from source.

Checklist

• Backend tests pass — cd backend && .venv/bin/pytest (567 passed, 1 new)
• Frontend checks pass — npm run test (167), npx tsc --noEmit, npx eslint ., npm run build
• If UI-observable, I ran it in the browser and confirmed it works — no UI change; the version is displayed by existing code
• Follows the architectural rules in CONTRIBUTING.md
• One migration for this PR if the schema changed — no migration, a config default and CI only
• This is not a security fix (those follow SECURITY.md)

This wants merging before v1.2.0 is tagged. The default has to read 1.2.0-src at the moment the tag is cut, and the new guard will block the release if it doesn't.

🤖 Generated with Claude Code