mirror of
https://github.com/Kaelio/ktx.git
synced 2026-07-04 10:52:13 +02:00
refactor(release): drop release-policy.json runtime dep and next branch (#180)
* chore: standardize daemon naming on "KTX daemon"
Replace inconsistent names ("KTX Python daemon", "KTX local embeddings
daemon", "KTX managed daemon", "Python daemon") with the single name
"KTX daemon" in CLI output, errors, command descriptions, test
assertions, smoke scripts, docs, AGENTS.md, issue templates, and
codecov flags. The daemon is a portable compute server with endpoints
for SQL analysis, semantic layer, LookML, database introspection, and
embeddings; the previous labels misrepresented it as embeddings-only or
exposed implementation details ("Python", "managed").
The "KTX Python runtime" concept (installed interpreter + packages) is
deliberately left as-is — it is a separate concept from the daemon
process.
* refactor(release): drop release-policy.json runtime dep and next branch
Strips the release-policy.json fallback from release-version.ts so the CLI
reads its version straight from packages/cli/package.json. dev → 0.0.0-private,
installed @kaelio/ktx → the real semver baked into the published package.json.
KtxCliPackageInfo collapses to { name, version, contextPackageName }; /health
no longer depends on version files surviving past a CI run.
Replaces the dual-branch (main + next) semantic-release model with a single-
branch model on main. rcs and stables interleave on the same branch via
{ name: 'main', prerelease: 'rc', channel: 'next' } / ['main']. Drops
@semantic-release/git and @semantic-release/changelog (nothing is committed
back to the repo on any channel) and the workflow's "Prepare next prerelease
branch" step plus the KTX_PRERELEASE_BRANCH plumbing. The git tag plus the
published npm artifact carry the version forward.
Updates docs/release.md, removes the two now-unused devDeps, regenerates
pnpm-lock.yaml. 611/611 @ktx/cli tests, 173/173 script tests, type-check,
biome, knip all clean.
* fix(release): don't throw on non-main branches at config-load time
knip loads .releaserc.cjs on every PR run, where GITHUB_REF_NAME is the
merge ref (e.g. 180/merge). The previous version of releaseBranches threw
immediately when the branch wasn't main, which made knip fail to evaluate
the config and then mis-flag @semantic-release/exec as an unused dep.
semantic-release already refuses to publish when the current branch doesn't
match a configured release branch, so the explicit throw was redundant.
Drop it (and the unused currentBranch helper) and replace the
"rejects releases from non-main" assertion with one that exercises a CI-
shaped GITHUB_REF_NAME and confirms the config loads.
This commit is contained in:
parent
da6d05ed55
commit
a11b9e9757
43 changed files with 142 additions and 387 deletions
|
|
@ -2,25 +2,24 @@
|
|||
|
||||
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 prerelease files back to the `next` branch.
|
||||
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
|
||||
|
||||
KTX has two npm release channels:
|
||||
`main` is the bleeding-edge branch. Every release runs from `main`; the
|
||||
dispatcher chooses the channel:
|
||||
|
||||
- `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.
|
||||
- `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.
|
||||
|
||||
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. You can publish an
|
||||
rc from `main` when you want to validate the current stable branch before a
|
||||
stable release.
|
||||
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.
|
||||
|
||||
Run stable releases only from `main`. The workflow rejects stable releases from
|
||||
other branches.
|
||||
The workflow rejects releases from any branch other than `main`.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
|
|
@ -59,16 +58,15 @@ publishing to npm.
|
|||
|
||||
1. Open **Actions** in GitHub.
|
||||
2. Select **KTX Release**.
|
||||
3. Select the branch to release from.
|
||||
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. For
|
||||
rc releases, it can create or update the `next` branch. It doesn't publish to
|
||||
npm and doesn't commit release files.
|
||||
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
|
||||
|
||||
|
|
@ -77,16 +75,15 @@ promoting to `latest`.
|
|||
|
||||
1. Open **Actions** in GitHub.
|
||||
2. Select **KTX Release**.
|
||||
3. Select the source branch to release from, including `main` when needed.
|
||||
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 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`.
|
||||
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
|
||||
|
||||
|
|
@ -101,26 +98,28 @@ Publish a stable release from `main` after you have validated an rc package.
|
|||
7. Run the workflow.
|
||||
|
||||
The workflow publishes `@kaelio/ktx` with `--access public --tag latest`, runs
|
||||
the published package smoke test, and creates a GitHub release. Stable releases
|
||||
don't commit release metadata back to `main`, because `main` is protected and
|
||||
requires changes through pull requests.
|
||||
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 `@semantic-release/npm` publishes the package. That script
|
||||
updates:
|
||||
prepare step before the exec publish command runs. That script updates the
|
||||
following files **inside the CI runner only**:
|
||||
|
||||
- `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. The semantic-release npm plugin publishes the generated
|
||||
`dist/public-npm-package` tree and writes the release tarball under
|
||||
`dist/artifacts/npm`. Stable releases use the updated metadata during the
|
||||
workflow run, but that generated metadata isn't committed back to `main`.
|
||||
The artifact packaging, readiness, and smoke-test scripts read
|
||||
`publicNpmPackageVersion` from `release-policy.json` within the same CI run.
|
||||
Nothing reads these files at runtime — the daemon and CLI rely on the
|
||||
published `package.json` (for the installed `@kaelio/ktx` package) or
|
||||
`packages/cli/package.json` (for dev-tree runs from this repo, which always
|
||||
report `0.0.0-private`). Because the metadata mutation never has to survive
|
||||
the run, no commit is pushed back to `main`. The git tag plus the published
|
||||
npm artifact carry the version forward.
|
||||
|
||||
The bundled Python runtime wheel also derives its version from
|
||||
`publicNpmPackageVersion`. Stable npm versions are reused as-is, and rc
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue