Release

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: kandev@X.Y.Z
• 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.

Contributor notices

The Release workflow has a notify_contributors checkbox. It defaults to false. When selected, the workflow calls the reusable notification workflow after GitHub Release, npm, Homebrew, and Scoop publication all succeed. Dry runs, desktop validation, Nightly, cancellation before the notification job starts, and publication errors skip the call. Cancellation after posting starts can leave partial notices; rerun with the exact tag to complete safely.

For manual notices or recovery, run Notify release contributors from the main ref. Leave release_tag empty to select the latest published Stable release. Enter an exact tag to select another release. The dry_run checkbox previews the same PR selection and comment text without posting.

The helper reads PR links from the release notes. It posts only to merged PRs from this repository that belong to the selected release tag. It excludes bots and maintainers from cliff.toml. The job token posts as github-actions[bot]. Only notices from that bot or a listed maintainer count as already sent.

Each comment includes a hidden release ID marker. Repeat runs skip comments with that marker and the exact unmarked notice used for v0.97.0. After a partial run, use the separate workflow with the exact tag. It skips confirmed notices and retries only missing notices. Wait for GitHub rate limits to clear before retrying.

Release PR ruleset bypass

A normal Stable release creates its branch and pull request with GITHUB_TOKEN. It uses RELEASE_PR_BYPASS_TOKEN only for an exact-head gh pr merge --admin.

Store this fine-grained personal access token in the protected release environment. Its owner must remain an organization administrator. Select only kdlbs/kandev and grant contents: write repository permission.

Record the token owner and expiration date. Rotate the environment secret before the token expires or the owner loses administrator access. The workflow must stop before tag creation when the token is missing or cannot bypass the ruleset.

After the merge, use GITHUB_TOKEN to read the PR state. Tag only the merge commit that GitHub reports after it appears on origin/main.

Workflow-control invariant: When a channel intentionally skips a job, every downstream job reachable through that dependency chain must use a status function such as !cancelled() plus explicit needs.<job>.result == 'success' checks. For a partial Stable release, preserve the existing signed tag and rerun with backfill_tag; never run a normal bump against an existing tag. Declare Stable complete only after publish-release, publish-npm, update-homebrew-tap, and update-scoop-bucket each succeed and their artifacts are verified—an aggregate green run can hide skipped publication jobs.

Required web, runtime, and desktop artifact uploads attempt up to three times, with waits of 30 seconds and 60 seconds between attempts. They fail explicitly when an expected file is missing. Desktop matrix targets use fail-fast: false so a transient upload failure does not cancel sibling targets, but publication still requires the complete matrix to succeed. Rerun a failed producer job in the same workflow run after a transient failure. If the signed tag already exists and the run remains partial, use backfill_tag for that tag after checking which channels already succeeded.