mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
41f52797de
* fix(release): point repository URLs at renamed GitHub repo The GitHub repo was renamed from Kaelio/ktx to Kaelio/ktx-ai-data-agents-context. semantic-release reads repositoryUrl from package.json's repository field and the @semantic-release/github plugin failed verifyConditions with EMISMATCHGITHUBURL because it no longer matched the live clone URL. Update every Kaelio/ktx reference to the renamed repo: package metadata (root + CLI repository/bugs/homepage), the codecov upload slugs and star-history slug in CI, the issue-template and security-advisory links, the release runbook, and all docs/install commands. * fix(release): derive semantic-release repositoryUrl from the CI repo @semantic-release/github exact-matches repositoryUrl against the live GitHub clone_url (no redirect following), so any repo rename re-breaks the release when repositoryUrl is the static package.json value. Derive repositoryUrl from the runner's GITHUB_REPOSITORY/GITHUB_SERVER_URL so it always tracks the current repo name. A future rename (including back to Kaelio/ktx) now resolves with no code change. Outside CI the option is omitted, so semantic-release falls back to package.json as documented. The package.json repository field stays ktx-ai-data-agents-context as npm-display metadata, decoupled from the release-time match.
155 lines
6.5 KiB
Markdown
155 lines
6.5 KiB
Markdown
# 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 in the CI workspace, publish the
|
|
package, and create the GitHub release. No files are ever committed back to
|
|
the repository — the git tag and the published npm artifact are the source of
|
|
truth for any released version.
|
|
|
|
## Release channels
|
|
|
|
`main` is the bleeding-edge branch. Every release runs from `main`; the
|
|
dispatcher chooses the channel:
|
|
|
|
- `rc` publishes prereleases such as `0.3.0-rc.1` to the npm `next` tag.
|
|
- `stable` publishes normal releases such as `0.3.0` to the npm `latest` tag.
|
|
|
|
Tag history on `main` interleaves rc and stable tags
|
|
(`v0.2.0 → v0.3.0-rc.1 → v0.3.0-rc.2 → v0.3.0 → …`). semantic-release uses the
|
|
prerelease tags to graduate to the next stable cleanly.
|
|
|
|
The workflow rejects releases from any branch other than `main`.
|
|
|
|
## Prerequisites
|
|
|
|
Before you publish, confirm these requirements:
|
|
|
|
- npm Trusted Publishing is configured for `@kaelio/ktx`.
|
|
- The trusted publisher points at the `Kaelio/ktx-ai-data-agents-context` repository and the
|
|
`.github/workflows/release.yml` workflow.
|
|
- The workflow keeps `id-token: write` permission so npm can verify the
|
|
GitHub Actions run through OpenID Connect.
|
|
- The repository has release metadata in `release-policy.json` for the current
|
|
public package line, such as `0.1.0-rc.1` or `0.1.0`.
|
|
- The repository has a stable baseline tag when you need semantic-release to
|
|
publish the first stable version as `0.1.0`.
|
|
|
|
If you rename the GitHub repository, the semantic-release run adapts on its
|
|
own: `scripts/semantic-release-config.cjs` derives `repositoryUrl` from the
|
|
runner's `GITHUB_REPOSITORY`, so `@semantic-release/github` always matches the
|
|
current clone URL. The one thing that does **not** auto-update is the npm
|
|
Trusted Publishing config — re-point it at the new repository name (plus
|
|
`release.yml`) on npm, or `npm publish --provenance` will fail OIDC
|
|
verification. The `repository` field in `package.json` is npm-display metadata
|
|
only and can stay whatever public name you prefer.
|
|
|
|
semantic-release doesn't support choosing an arbitrary first `0.x` stable
|
|
release. If KTX has no stable tag yet and you need the first stable release to
|
|
be `0.1.0`, create and push the baseline tag once before running the live
|
|
stable workflow:
|
|
|
|
```bash
|
|
root_commit="$(git rev-list --max-parents=0 HEAD | tail -n 1)"
|
|
git tag v0.0.0 "${root_commit}"
|
|
git push origin v0.0.0
|
|
```
|
|
|
|
KTX follows the same versioning schema as the main Kaelio release workflow:
|
|
breaking-change and `major` commit markers create a minor release, not an
|
|
automatic major release. A major version requires an intentional manual release
|
|
path.
|
|
|
|
## 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 `main`.
|
|
4. Set **release_kind** to `rc` or `stable`.
|
|
5. Set **publish_live** 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 push any tags.
|
|
|
|
## 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 `main`.
|
|
4. Set **release_kind** to `rc`.
|
|
5. Leave **publish_live** set 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 pushes the
|
|
`vX.Y.Z-rc.N` tag.
|
|
|
|
## 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. Leave **release_kind** set to `stable`.
|
|
5. Leave **publish_live** set 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 pushes the
|
|
`vX.Y.Z` tag. semantic-release graduates from the most recent rc tag, so the
|
|
prior rc lineage is consumed cleanly.
|
|
|
|
## Release metadata
|
|
|
|
semantic-release calls `scripts/update-public-release-version.mjs` during the
|
|
prepare step before the exec publish command runs. That script rewrites the
|
|
following files in lockstep:
|
|
|
|
- `package.json` and `packages/cli/package.json` with the semantic-release
|
|
version.
|
|
- `python/ktx-daemon/pyproject.toml` and `python/ktx-sl/pyproject.toml` with
|
|
the same version, normalized for PEP 440 (e.g. `0.1.0-rc.2` →
|
|
`0.1.0rc2`). Branch-prefixed npm releases skip this step because they are
|
|
not published to PyPI.
|
|
- `release-policy.json` with the npm publish settings, release mode, and
|
|
published package smoke-test version. The package version itself is not
|
|
stored here; it is derived from `packages/cli/package.json.version` by
|
|
`scripts/public-npm-release-metadata.mjs`, so there is only one place that
|
|
owns the version.
|
|
|
|
The `@semantic-release/git` plugin then commits these files back to `main`
|
|
with the release tag (see `scripts/semantic-release-config.cjs`). As a
|
|
result, the dev tree always reflects the most recently published version —
|
|
there is no sentinel pin. `ktx --version` and the bundled Python wheel both
|
|
report whatever was last released.
|
|
|
|
At runtime the CLI reads its version from its own `package.json` via
|
|
`getKtxCliPackageInfo()` (`packages/cli/src/cli-runtime.ts`); the Python
|
|
daemon reads its version from installed-package metadata via
|
|
`importlib.metadata.version()` (`python/ktx-daemon/src/ktx_daemon/__init__.py`).
|
|
|
|
The bundled Python runtime wheel also derives its version from the same
|
|
single source. Stable npm versions are reused as-is, and rc versions are
|
|
normalized to Python's version format. For example, `0.1.0-rc.2` becomes
|
|
`0.1.0rc2` in the `kaelio-ktx` wheel filename and wheel metadata.
|
|
|
|
## npm authentication
|
|
|
|
The release workflow publishes through npm Trusted Publishing. It doesn't use
|
|
an `NPM_TOKEN` secret, and the publish step doesn't set `NODE_AUTH_TOKEN`.
|
|
|
|
If npm returns an authentication error, check the Trusted Publishing settings
|
|
for the `@kaelio/ktx` package before adding token-based authentication back to
|
|
the workflow.
|