Release & Versioning

Release & Versioning

Kandev Stable releases use a single SemVer X.Y.Z shared across all distribution channels. npm also has an explicit prerelease-only nightly channel; it is not part of the unified Stable artifact set.

Version targets

• apps/cli/package.json version → X.Y.Z
• npm main package: [email protected]
• npm runtime packages: @kdlbs/runtime-{platform}@X.Y.Z (5 platforms; declared as optionalDependencies in main package)
• Git tag: vX.Y.Z (three-part; legacy vM.m tags normalize to M.m.0)
• Homebrew formula: kdlbs/homebrew-kandev Formula/kandev.rb version "X.Y.Z"
• Scoop bucket: kdlbs/scoop-kandev bucket/kandev.json version, URL, and hash
• GitHub release: vX.Y.Z with standard platform archives kandev-{platform}.tar.gz, full offline archives kandev-{platform}-full.tar.gz, checksums, Windows ZIP equivalents, remote helper assets, and runtime-size-report.md

Stable default archive names contain the standard runtime: host kandev, host agentctl, and remote-helpers.json. The -full archives also contain all four remote helper executables. Stable npm packages, Homebrew, Scoop, winget, Chocolatey, and Desktop use standard archives. Containers and npm Nightlies stay full. Desktop keeps one standard installer and updater track.

npm, Homebrew, and Scoop are sibling channels, not chained. All three consume the same GitHub release artifacts; none depends on another package-manager channel.

For npm Nightly, Stable X.Y.Z plus a full main SHA produces X.Y.(Z+1)-nightly.sha<first-12-lowercase-hex>. kandev and all five runtime packages publish at that exact version under npm's nightly dist-tag. Nightly never moves latest and creates no Git tag, GitHub Release, Homebrew formula, Scoop bucket update, Desktop feed/build, or container tag.

Release flow

Stable runs entirely in CI via .github/workflows/release.yml, triggered by a maintainer from the GitHub Actions UI:

1. Maintainer clicks "Run workflow" → keeps channel=stable → picks bump (patch/minor/major) → optional dry_run or desktop_validation_only.
2. prepare job bumps version + regenerates CHANGELOG, opens release PR, squash-merges, tags vX.Y.Z.
3. build-web, build-bundles, build-remote-helpers, build-desktop, and both Docker builds create the channel inputs.
4. publish-release promotes staged standard archives to the existing default names, publishes full archives and helper assets, then attaches checksums, the size report, desktop artifacts, and notes.
5. publish-npm publishes 5 @kdlbs/runtime-* packages + main kandev package to npmjs.
6. update-homebrew-tap pushes updated Formula/kandev.rb to kdlbs/homebrew-kandev via SSH deploy key.
7. update-scoop-bucket pushes updated bucket/kandev.json to kdlbs/scoop-kandev via its SSH deploy key.