ktx/docs/release.md

KTX release runbook

This runbook covers the maintainer workflow for publishing @kaelio/ktx to npm through GitHub Actions. The workflow uses semantic-release to choose the next version, update release metadata, publish the package, create the GitHub release, and commit the release files back to the repository.

Release channels

KTX has two npm release channels:

• rc publishes prereleases such as 0.1.0-rc.2 to the npm next tag.
• stable publishes normal releases such as 0.1.0 to the npm latest tag.

Run rc releases from the source branch you want to publish. The workflow creates or updates the next prerelease branch from that source branch before running semantic-release, because semantic-release requires a dedicated prerelease branch in addition to the stable main branch.

Run stable releases only from main. The workflow rejects stable releases from other branches.

Prerequisites

Before you publish, confirm these requirements:

• The repository has an Actions secret named NPM_TOKEN.
• NPM_TOKEN is a granular npm token that can publish @kaelio/ktx.
• The token can publish non-interactively if the npm account or package uses two-factor authentication for writes.
• The repository has a baseline semantic-release tag for the latest published package version, such as v0.1.0-rc.1.

If no baseline tag exists, semantic-release treats the run as the first release and may choose a version that doesn't match the currently published package.

Dry-run a release

Use a dry-run to verify the next version and generated release notes without publishing to npm.

1. Open Actions in GitHub.
2. Select KTX Release.
3. Select the branch to release from.
4. Set release_kind to rc or stable.
5. Leave publish_live set to false.
6. Optional: Set force_release to true when you need a patch release even if semantic-release doesn't find a releasable commit.
7. Run the workflow.

The dry-run uses the same semantic-release configuration as a live release. For rc releases, it can create or update the next branch. It doesn't publish to npm and doesn't commit release files.

Publish an rc release

Publish an rc release when you need a prerelease package for validation before promoting to latest.

1. Open Actions in GitHub.
2. Select KTX Release.
3. Select the source branch to release from.
4. Set release_kind to rc.
5. Set publish_live to true.
6. Optional: Set force_release to true.
7. Run the workflow.

The workflow merges the selected source branch into next, publishes @kaelio/ktx with --access public --tag next, runs the published package smoke test, creates a GitHub release, and commits CHANGELOG.md, package.json, and release-policy.json on next.

Publish a stable release

Publish a stable release from main after you have validated an rc package.

1. Open Actions in GitHub.
2. Select KTX Release.
3. Select main.
4. Set release_kind to stable.
5. Set publish_live to true.
6. Optional: Set force_release to true.
7. Run the workflow.

The workflow publishes @kaelio/ktx with --access public --tag latest, runs the published package smoke test, creates a GitHub release, and commits the release metadata.

Release metadata

semantic-release calls scripts/update-public-release-version.mjs during the prepare step. That script updates:

• package.json with the semantic-release version.
• release-policy.json with publicNpmPackageVersion, npm publish settings, and the published package smoke-test version.

The artifact packaging and readiness scripts read publicNpmPackageVersion from release-policy.json, so manual version edits in build scripts aren't needed for rc releases.

Trusted Publishing follow-up

This workflow uses NPM_TOKEN today. Move to npm Trusted Publishing after the final publish command path is verified for the package manager and workflow filename configured in npm package settings.