Skip to content

feat: CalVer versioning from git tags, version visible, Linux PR builds (ADR-0013) - #188

Merged
jonocodes merged 1 commit into
mainfrom
feat/calver-versioning
Nov 14, 2026
Merged

jonocodes merged 1 commit into
mainfrom
feat/calver-versioning

Conversation

@jonocodes

Copy link
Copy Markdown
Owner

Implements the versioning plan. ADR-0013: CalVer vYYYY.M.MICRO, with the git tag as the only source of truth.

Summary

Scheme. v2026.11.0, v2026.11.1, … then v2026.12.0. That's the UTC year, the unpadded month, and a counter of releases within the month starting at 0. Release candidates take -rcN and publish as prereleases. YYYY.MM.DD was rejected because a second release on the same day would need a fourth number, and macOS's CFBundleShortVersionString allows only three.

One source. Every version now comes from the git tag:

 pyproject.toml
-  version = "0.0.1"
+  dynamic = ["version"]   # setuptools-scm → daemon/deckd/_version.py (gitignored)
 daemon/deckd/__init__.py
-  __version__ = "0.0.1"
+  __version__ = _read_version()   # from _version.py; "0+unknown" if never installed
 daemon/deckd/diagnostics.py   "version": "0.0.1"  →  __version__
 package.json, client/package.json   "version": "0.0.1"  →  (removed; both private)
 flake.nix   passes 0+git.<date>.g<rev>; exported modules default to that package
git tag                     → package version
v2026.11.0 (exact)          → 2026.11.0
3 commits after             → 2026.11.0.post1.dev3+g<sha>
v2026.12.0-rc1              → 2026.12.0rc1
non-CalVer tags (verify/…, v0.0.0-*)   ignored
no git (bare source tree)   → 0+unknown

Visible. The version now appears in /health (readable before auth, like the rest of it), /diag, deckd --version, deckctl --version and deckctl status, and as a "deckd version" row in the client settings diagnostics.

Releasing.

just release
  fetch tags; require a clean tree with HEAD == origin/main
  tag = scripts/next_version.py     # v2026.11.0 → v2026.11.1 → v2026.12.0
  show tag + commit, ask y/N
  git tag -a $tag && git push origin $tag   → both release workflows

CI. release-linux.yml now matches what #186 did for macOS:

  • PRs that touch Linux packaging run the build, distro-floor and smoke tests, and never publish.
  • Manual runs get a publish on/off switch.
  • Permissions are read-only by default.

Release checkouts use full history so the frozen apps see the tag, and the Linux job asserts that the tarball's --version equals the tag.

Evidence

  • pytest: 842 passed (+6 test_next_version.py, plus version assertions on /health, /diag, --version and deckctl status). pyright is clean, tsc is clean, and the client unit tests pass (393).
  • Version derivation in a scratch clone (real pip install -e):
    tag v2026.11.0:   deckd 2026.11.0 | deckctl 2026.11.0
    one commit later: deckd 2026.11.0.post1.dev1+g005e8b5
    live /health:     "version": "2026.11.0.post1.dev1+g005e8b5"
    
    Edge cases checked: no tags, rc tags, verify/…, v0.0.0-test-115 (which crashed setuptools-scm until the tag match was narrowed to CalVer-shaped tags), and no .git at all.
  • Frozen app: just build-linux-portable builds in the manylinux container, and bin/deckd --version prints the git-derived version.
  • Nix: nix flake check passes. nix build .#deckd then deckd --version prints 0+git.20261114.gaf60623…. Evaluating the modules confirms that NixOS, home + GNOME imported together, and a user's own package override all resolve correctly.

Merge Danger

Door: two-way

No releases exist yet. The first just release creates v2026.11.0.

Blast Radius: build/release

  • Nix: the client derivation's version is pinned to "0" so its npm-deps download stays cached across commits, and npmDepsHash was updated because the lockfile lost its version line.
  • Dev builds show a placeholder version (0.post1.devN+unknown.g<sha>) until the first CalVer tag exists. Editable installs show the version from the last just setup.
  • macOS PR builds run on this PR because it touches app_bundle.py and pyproject.toml, so the new PR builds get exercised here.

…lds (ADR-0013)

Releases are tagged vYYYY.M.MICRO (UTC year + unpadded month, MICRO counts
releases within the month from 0; rcs take -rcN). YYYY.MM.DD was rejected:
a same-day second release needs a fourth component, which breaks the macOS
three-integer CFBundleShortVersionString.

The tag is now the only source of truth:
- setuptools-scm derives the version (no-guess-dev: exactly the tag on a
  tag, 2026.11.0.post1.dev3+g<sha> after it) and writes deckd/_version.py
  at install; it matches only CalVer-shaped tags, skipping
  verify/61-touch-targets and the v0.0.0-* rehearsals.
- The hard-coded 0.0.1 copies are gone (pyproject, __init__, /diag,
  package.json x2).
- The flake passes 0+git.<date>.g<rev> (no .git in the store); exported
  NixOS/home-manager modules default to the flake's own versioned package
  via one keyed module, so importing several defines it once.
- Release checkouts use full history so the frozen apps carry the tag; the
  Linux job asserts the tarball's --version equals the tag.
- build-linux-portable mounts the main git dir when run from a worktree.

Visible in /health, /diag, `deckd --version`, `deckctl --version` /
`status`, and the client settings diagnostics.

`just release` computes the next tag (scripts/next_version.py, tested),
checks the tree is clean and at origin/main, confirms, then tags + pushes.

release-linux.yml gains PR builds for Linux packaging paths (build, floor,
smoke; never publish), a publish toggle for manual runs, and read-only
default permissions, mirroring release-macos.yml.
@jonocodes
jonocodes merged commit 182022d into main Nov 14, 2026
10 checks passed
@jonocodes
jonocodes deleted the feat/calver-versioning branch November 14, 2026 23:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant