Kitaru Release

Release Kitaru

Use the current workflows as the source of truth:

• Core: .github/workflows/release.yml
• Plugins: .github/workflows/release-plugins.yml
• Python package inventory: release/release-units.toml
• TypeScript release set: release/typescript.md and .github/workflows/release-typescript.yml
• Frontend: zenml-io/zenml-frontend-monorepo/.github/workflows/release-kitaru-ui.yml
• Follow-up skills release: skills-release

Read AGENTS.md. Read plugins/AGENTS.md and plugins/DEVELOPMENT.md for plugin changes. Read FRONTEND-TESTING.md for core or UI work.

Do not create a tag, dispatch a publishing workflow, approve an environment, or publish an artifact without explicit user confirmation. A request to prepare a release authorizes a release PR only.

Select the release shape

Ask only for choices that cannot be derived from the repository and registries.

1. Core: Release kitaru, the selected UI, public images, the managed image, and Helm from one core tag.
2. One plugin: Release one selected Python plugin distribution. Do not release the UI or core.
3. All plugins: Inspect and prepare every plugin release unit independently.
4. Coordinated: Release core with its selected UI, then publish plugins that depend on that core version.

There is no separate bundle tag. The core tag publishes the Python package and deployables in one workflow.

Confirm the selected distributions, versions, frontend tag, publication order, and release commit before editing.

Discover release impact

Fetch current remote state and load the release inventory:

git fetch origin --prune --tags
uv run --no-project --with packaging==26.2 \
  python scripts/release_units.py list --format json

For every selected unit, resolve its latest published tag. Compare that tag with origin/develop and inspect merged PRs in the range with git log, git diff, and gh pr view. Derive directly changed core and plugin units from impact-paths in release/release-units.toml. Read requires:* labels as release follow-up metadata, together with Release context, linked work, and existing changelog fragments in changelog.d/. A directly changed unit does not need a matching label when it will be published in the next applicable release. If its publication is intentionally deferred past that release, attach its exact release-label and record the intended timing in Release context.

For one plugin, start at that plugin's previous tag. For all plugins, calculate a separate range for every plugin release unit. requires:plugins means every unit is expected; report a unit with no implementation change as a red flag and require an explanation in the release PR.

For core, collect requirements for frontend, plugins, skills, ZenML docs, website, examples, and additional context from source PRs. Read linked repositories with gh or existing local checkouts. Do not write to them.

Compare declared follow-ups with the actual diff and PR context. Report unknown, conflicting, or stale signals. The diff identifies direct units; labels record deferred publication or other work that the Kitaru diff cannot show. Repository state decides what can be released.

For core, collect every merged PR label in the range and use the latest published stable core version as the input to the deterministic version rule:

uv run --no-project --with packaging==26.2 \
  python scripts/release_units.py propose-core-version \
  --latest-version <latest-stable-version> \
  --label <first-merged-pr-label> \
  --label <second-merged-pr-label> ...

Pass every label occurrence; do not summarize or discard labels before running the command. A Breaking Change label advances a pre-1.0 core to the next minor version and a post-1.0 core to the next major version. Without that label, the command advances the patch version. The version in pyproject.toml may contain +dev; it is a development placeholder and is never the input or release proposal. PR prose about an expected dependency floor does not override the command result.

Before editing, rerun the command with --candidate <proposed-version> and require it to pass. Do not prepare a different core version.

Propose explicit versions and changelog entries after discovery. Check PyPI versions and Git tags before proposing a version, and never reuse a published version. Get the user's acceptance before editing release metadata.

Separate implementation from release preparation

Feature PRs leave existing plugin package versions and server default requirements/display versions unchanged. Put behavior changes in the package's Unreleased changelog section. The release-preparation PR selects package versions and updates all matching default-catalog metadata together. New packages require initial metadata, but becoming a server default remains an explicit release decision.

Follow the development dependency policy in plugins/DEVELOPMENT.md. Plugins compatible with published core keep their supported minimum. A plugin requiring unreleased core uses an exact dependency on the current root development version, such as kitaru==0.25.0+dev, and records the needed core change in Release context.

Before changing core to its selected release version, inspect every plugin's core dependency. Replace each resolved development pin with the selected compatible release floor, such as kitaru>=0.26.0, preserving extras and compatible upper bounds. Do not guess the future version in the feature PR. An unresolved development pin blocks release preparation; account for every affected plugin and its publication timing. A plugin-only release can replace the pin only when a published core contains the required change.

Regenerate plugins/uv.lock after these conversions. Verify the selected wheels' Requires-Dist metadata contains no development placeholder or local checkout dependency before handing over publication commands.

Inspect the TypeScript packages separately from the Python inventory. Include their lockstep release when their changes require publication. Inspect the Kitaru skills repository for a pending release and record its own version and compatibility requirements.

Apply version rules

• Use canonical PEP 440 for Python: X.Y.Z or X.Y.ZrcN.
• The core workflow converts X.Y.ZrcN to X.Y.Z-rc.N for Docker and Helm.
• Use vX.Y.Z or vX.Y.Z-rc.N as the frontend workflow input.
• The frontend release tag is kitaru-ui-vX.Y.Z or kitaru-ui-vX.Y.Z-rc.N.
• Never reuse a published version or move a published tag.
• Increment the RC number for another candidate of the same target.
• Remove the RC suffix to accept a candidate without changing X.Y.Z.

For pre-1.0 plugins, use a patch when the public API and observable output stay compatible for existing supported inputs. Use a minor for new capabilities or breaking behavior. Importer output includes session grouping, IDs, node structure, field mappings, normalized values, and incomplete or failed trace handling.

Release or select the frontend

Perform this section before the core preparation PR when the core needs a new UI release.

1. Inspect zenml-io/zenml-frontend-monorepo and select an exact commit on main.
2. Confirm its Kitaru UI checks pass.
3. Select a stable frontend version input, such as v0.4.0, for an official core release.
4. Ask for explicit confirmation before publishing.
5. Emit minimal tag commands for the frontend repository, using publication-handoff.md. Use HEAD only when main points to the reviewed commit:

git checkout main
git tag kitaru-ui-v0.4.0 HEAD
git push origin kitaru-ui-v0.4.0

The tag push starts release-kitaru-ui.yml.

6. Capture and monitor the exact run:

gh run list --repo zenml-io/zenml-frontend-monorepo \
  --workflow release-kitaru-ui.yml --limit 5
gh run view <run-id> --repo zenml-io/zenml-frontend-monorepo

7. Verify the release tag and both assets:

gh release view kitaru-ui-v0.4.0 \
  --repo zenml-io/zenml-frontend-monorepo

Require kitaru-ui.tar.gz and kitaru-ui.tar.gz.sha256. Verify the workflow ran at the reviewed commit and the release is stable. The frontend workflow derives its release channel from whether the selected commit is on main; official core releases require a stable bundle.

If the user asks only for a preparation PR, do not push the frontend tag or dispatch the frontend workflow. The user can explicitly select an expected frontend tag before it exists. Mark asset verification as pending and do not create the core tag until both assets exist.

Prepare a core release PR

Create a branch from current origin/develop. Preserve unrelated work in the active checkout.

1. Set [project].version in pyproject.toml.
2. Add a concise release-specific fragment to changelog.d/ when needed.
3. Preview the release section with uv run python scripts/changelog_fragments.py build --version <version> --draft, then run it without --draft. This moves every fragment into a new CHANGELOG.md section for the selected version and deletes the fragment files.
4. Create releases/python/kitaru/<version>.toml:

schema-version = 1
kitaru-version = "<python-version>"
ui-tag = "<kitaru-ui-tag>"

5. Resolve plugin development dependencies to the selected core version, then run uv lock and uv lock --project plugins. Keep unrelated exclude-newer timestamp churn out of the diff.
6. Run uv run python scripts/generate_openapi.py and commit openapi/openapi.json.
7. If a default plugin version changes, update every matching server catalog requirement and display version. The release inventory validates these values against the package manifest.

Read default membership from release/release-units.toml. Do not copy a fixed plugin count or a retired plugin name into the skill.

Check the standalone quickstart dependency floor and lockfile under examples/python/pydantic_ai_ticket_resolver/. Its README uses uv sync --frozen, so changing only the dependency floor does not update the installed version. Refresh both files to a published compatible core version, retaining unrelated dependency pins:

uv add --project examples/python/pydantic_ai_ticket_resolver --no-sync \
  --upgrade-package "kitaru==<published-version>" \
  "kitaru[cli,mcp,server,worker]>=<published-version>"

With the local test PostgreSQL available, run uv sync --frozen and uv run --frozen python scripts/run_ci_e2e.py from the example directory before installing candidate wheels. The published-dependency run and the candidate-wheel run verify different installation paths. Preserve the existing lockfile cutoff when no unrelated dependency update is needed.

Do not put an unpublished version or a local wheel path into the public quickstart lockfile. If the example requires the upcoming release, record its dependency refresh and frozen end-to-end check as a post-publication follow-up; candidate-wheel success alone does not complete it.

The frontend declaration contains only the schema version, Kitaru version, and trusted frontend tag. The workflow downloads and verifies the published checksum.

Prepare a plugin-only release PR

Select the distribution from release/release-units.toml.

1. Update only the selected package version:

uv version --project plugins --package <distribution> <version> --no-sync

2. Update its Kitaru compatibility range when required.
3. Update its package changelog.
4. Run uv lock --project plugins.
5. Leave every unselected package unchanged.

For a default-catalog plugin, update matching server requirements and display versions in this release-preparation PR. The current inventory validator requires them to match the selected package version. Feature PRs avoid that coupling by leaving both versions and default pins unchanged.

For a coordinated release, prepare core and plugin versions together. Tag core first. After the core publish-python job succeeds and the exact version is available on PyPI, tag dependent plugins. Core deployables and other jobs can continue while plugins publish. A default pin may reference a queued plugin version when the repository's pending-default behavior is available and verified. An independent plugin release uses an already-published compatible core.

Patch an existing plugin release line

Use the unit's maintenance branch from release/release-units.toml, named release/<plugin>/<major.minor>. Confirm the branch exists and the requested version is the next unused patch version. The plugin workflow accepts a tag whose commit belongs to develop or that exact maintenance branch.

When the same bug exists on develop, merge the implementation there first. Then cherry-pick only its implementation commit onto a fix branch based on the maintenance line:

git fetch origin --prune --tags
git switch --track origin/release/langfuse/0.4
git switch -c fix/langfuse-0.4.1
git cherry-pick <implementation-commit>

When the bug only affects a superseded line, create the fix branch from that maintenance line and implement the fix there. Forward-port it only if the same bug exists on develop.

On the fix branch:

1. Bump only the selected plugin to the patch version.
2. Update its changelog and plugins/uv.lock.
3. For a default-catalog plugin, update matching bootstrap requirements and display versions only when that maintenance line uses the patched version.
4. Run the selected plugin's focused tests, release inventory validation, and artifact smoke.
5. Open the PR against the maintenance branch, not develop.

After the maintenance PR merges, resolve its exact merge commit and prepare the namespaced tag command. Do not push the tag without explicit authorization:

Use HEAD only when the maintenance branch points to that reviewed commit; otherwise use its literal SHA:

git checkout release/langfuse/0.4
git tag python/kitaru-langfuse-importer/v0.4.1 HEAD
git push origin python/kitaru-langfuse-importer/v0.4.1

Leave a newer package version and default-catalog declaration on develop unchanged when patching a superseded line.

Validate the preparation

Always run:

git diff --check
just check
uv run --no-project --with packaging==26.2 python scripts/release_units.py validate

For core metadata and UI selection, run:

uv run python scripts/release_ui.py --version <core-version>
uv run pytest -q tests/scripts/test_release_ui.py tests/scripts/test_release_units.py

For plugin metadata, dependencies, or default pins, run:

uv run --project plugins ruff format --config plugins/pyproject.toml --check plugins
uv run --project plugins ruff check --config plugins/pyproject.toml plugins
uv run --project plugins ty check --project plugins
uv run --project plugins pytest -q -c plugins/pyproject.toml plugins/tests tests/server/test_default_plugins.py
just plugin-artifact-smoke

Review the final version, frontend tag, dependency ranges, exact default pins, changelog, file list, and validation results.

Open the preparation PR

Commit only the release files. Push the branch and open a draft PR to develop.

Include:

• release shape and versions
• source PRs included for each release unit
• frontend tag and asset status for core
• dependency and default-pin decisions
• plugin coverage and explanations for missing units in an all-plugin release
• linked skills, ZenML docs, website, examples, and other follow-ups
• validations run
• exact post-merge tag and follow-up order
• ## Reviewer Notes with a concrete review path

Stop after the PR unless the user explicitly asks to publish.

After the PR merges, verify its exact merge commit, then emit the publication command handoff in the PR and final response exactly as publication-handoff.md specifies: grouped by repository and source branch, covering every selected Python plugin, the TypeScript release set when selected, any new frontend release, manual main promotion, and the Kitaru skills release handoff. Do not execute publication commands during preparation.

Rehearse before publication

Manual dispatch builds and validates without publishing. These are agent-side rehearsal commands, not part of the user-facing tag handoff.

Core:

gh workflow run release.yml --repo zenml-io/kitaru --ref <reviewed-branch-or-tag> \
  -f package-tag=python/kitaru/v<python-version>

Plugin:

gh workflow run release-plugins.yml --repo zenml-io/kitaru --ref <reviewed-branch-or-tag> \
  -f package-tag=python/<distribution>/v<python-version>

Use an existing branch or tag that resolves to the reviewed eligible commit. Confirm the run's headSha matches that commit, inspect its artifacts, and confirm no publishing job ran.