kandev/docs/public/release-process.md

title, description

title	description
Release Process	Understand Kandev's automated version, changelog, runtime bundle, desktop, npm, GitHub, and Homebrew release flow.

Release Process

Kandev uses one semantic version for the CLI, native runtime bundles, desktop artifacts, npm packages, Git tag, GitHub release, and Homebrew formula. Releases are driven by the Release GitHub Actions workflow, not by manually publishing individual channels.

Before a release

1. Confirm required checks pass on main.
2. Review user-visible changes and update docs/public/** plus changelog inputs.
3. Verify platform-sensitive launcher, agentctl, and desktop changes on their target systems.
4. Confirm publishing credentials, signing/notarization secrets, npm access, and Homebrew tap access are healthy.
5. Avoid starting a release while another version or release PR is active.

Run the workflow

In GitHub Actions, open Release, choose Run workflow, select patch, minor, or major, and optionally enable dry-run validation.

The workflow validates the requested bump, computes the next version, updates the package version and changelog, opens and merges the release PR, creates the vX.Y.Z tag, then builds and publishes the release channels.

Do not create a competing tag or edit generated release files while the workflow is running.

Artifacts and channels

The release produces platform runtime bundles containing the unified kandev binary and agentctl helpers. npm installs a small launcher plus one platform-selected @kdlbs/runtime-* optional package. Homebrew consumes GitHub release tarballs. The Tauri desktop build embeds the matching runtime before packaging and signing.

Supported runtime targets and artifact shapes are maintained in apps/cli/README_internal.md and the release scripts. When adding a platform, update build matrices, npm optional dependencies, archive names, launcher mapping, tests, checksums, desktop resources, and Homebrew handling together.

Signing and publishing

Desktop signing/notarization and package publishing depend on repository secrets. Logs and artifacts must not expose signing material. A failure after the tag exists is a release-repair incident: inspect which channels published before rerunning or changing tags.

Never overwrite an already published semantic version. Fix the pipeline and publish a new patch when immutable package registries or release assets require it.

Verify the release

After publication:

• check the GitHub release, notes, checksums, and expected platform archives;
• install with npx kandev@latest in a clean directory;
• verify a Homebrew install or upgrade;
• launch the desktop artifact on signed target platforms;
• run kandev --version and a minimal first task;
• confirm the Updates screen sees the new release;
• verify public docs describe the shipped behavior rather than unreleased main where it matters.

Rollback and repair

Published artifacts are immutable evidence. If a release is broken:

1. stop or disable the failing publication stage if it is still running;
2. record which channels and architectures are affected;
3. preserve logs and release metadata;
4. fix on main with focused tests;
5. publish a new patch release;
6. document upgrade or mitigation steps for affected users.

For the exact workflow implementation, inspect .github/workflows/release.yml, scripts/release/, apps/cli/README_internal.md, and the desktop signing documentation in the repository. These internal files are more detailed but are not the user-facing product contract.