Version number and tag semantics for the first stable release #980

Activity

1. nick-potts

   added

   wayfinder:grillingHITL decision ticketHITL decision ticket

   on Sep 23, 2026
2. nick-potts

   marked this as blocking on Sep 23, 2026

   • Keep only stable and beta Release Channels #990
3. nick-potts

   self-assigned this

   on Sep 24, 2026
4. nick-potts commented on Sep 24, 2026

   

   nick-potts

   on Sep 24, 2026

   ContributorAuthor

   More actions

   Resolution

   v0.1.2-beta.41 (ployz2, last)
           │  cutover to getployz/ployz
           ▼
   v0.2.0-beta.1 … N  ──►  v0.2.0  first stable — the stable promise starts
                              │  later 0.x releases keep the promise
                              ▼
                           v1.0.0  once users have validated it; semver, may break
   

   1. First stable tag is v0.2.0. 1.0 is reserved for after real-user validation.
   2. Betas before it are v0.2.0-beta.N. The v0.1.2-beta line ends at .41.
   3. Betas are cut in getployz/ployz after the cutover. The compiled release sources (ployzd installer, CLI bootstrap, install.sh) switch to getployz/ployz as part of the cutover, so no daemon covered by the promise ever points at ployz2. The cutover therefore happens before v0.2.0-beta.1.
   4. Promise range: from 0.2.0 through every later 0.x release. Versioning follows semver: 1.0 may break (probably won't), and must say so if it does. Recorded in core/DESIGN.md → Stable promise.
   5. Tag → channel mapping (release-tag.sh is unchanged): vX.Y.Z → stable, vX.Y.Z-beta.N → beta; every other suffix is rejected.
   6. Pointers only move forward. promote-release.sh advances a pointer only when the published tag is higher by semver, so an older-line fix never moves stable backwards and stays reachable by exact pin. This is what makes stable "the highest stable": the resolver stays a single pointer read with no GitHub listing.
   7. beta = max(latest beta, latest stable). A stable Publish also advances beta when it is higher.
   8. Upgrading through a channel never downgrades. stable/beta keep the installed daemon when it is higher than the pointer; only an exact version moves a Machine backwards. (Today replacement_required replaces whenever the versions differ.)
   9. Never a pre-release from stable: guaranteed by 5 and 6 (the pointer only ever receives stable tags). The resolver also rejects a pre-release read from stable, as a defensive check.
   10. Crossing a breaking release through a channel: decided when 1.0 is known to break. At that point ployz.sh/stable can stay on the 0.x line for 0.x daemons and 1.0 can get a new pointer name. It is not needed before then.

   Findings this corrected: the resolver reads the ployz.sh/<channel> pointer and does not pick the highest version, and the pointer was "last published". machine init/add install the CLI's own version (CARGO_PKG_VERSION), not a channel.

   Implementation belongs to Keep only stable and beta Release Channels (6–9) and Cut over to getployz/ployz (3). check-release-tag.sh also drops its SDK package.json check under the cleanup spec.
5. nick-potts

   closed this as completedon Sep 24, 2026