apunkt/ktx
1
0
Fork 0
mirror of https://github.com/Kaelio/ktx.git synced 2026-06-07 07:55:13 +02:00
Code Issues Projects Releases Packages Wiki Activity
ktx/docs/release.md
Andrey Avtomonov b565e44a22
feat: add claude-code llm backend with runtime port (#115) 
* docs: revise claude-code ingest backend spec

* docs: keep claude-code spec focused on ingest

* docs: expand claude-code spec to full llm parity

* Refine claude-code backend spec after adversarial review iteration 1

* Refine claude-code backend spec after adversarial review iteration 2

* Refine claude-code backend spec after adversarial review iteration 3

* feat: recognize claude-code llm backend

* feat: add ktx llm runtime port

* feat: add claude-code llm runtime

* feat: route non-agent llm calls through runtime

* feat: run ingest agents through llm runtime

* feat: support claude-code setup and status

* test: verify claude-code backend runtime

* docs: add claude-code backend v1 runtime plan

* fix: close claude-code runtime isolation checks

* fix: warn on claude-code prompt caching during setup

* chore: verify claude-code v1 closure

* docs: add claude-code backend v1 isolation closure plan

* fix: update claude-code ingest setup guidance

* docs: add claude-code backend v1 ingest guidance closure plan

* docs: align claude-code isolation spec with sdk metadata

* test: cover claude-code host discovery metadata

* fix: tolerate claude-code host discovery metadata

* docs: clarify claude-code host discovery metadata

* docs: add claude-code auth-probe isolation fix plan

* chore: prepare kaelio ktx rc1 release

* chore: add semantic release workflow

* fix: unblock ci checks

* chore(release): 0.1.0-rc.1

* feat: add Claude Code model selection to setup

* fix: keep git maintenance attached in local repos
2026-05-16 12:06:34 +02:00

3.5 KiB
Raw Blame History

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 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. 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 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 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.

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.