kub-version

1. Overview

kub-version centralizes KUB release version management. It provides three operations:

  • show: display detected versions from source files

  • check: validate cross-file version consistency (used by CI)

  • bump: update all managed version files from one command

This avoids embedding release logic directly in CI YAML and keeps version policy in tested Python code.

2. Installation

kub-version is installed with the main Python package:

# development install
uv pip install -e .

# then
kub-version --help

3. Synopsis

kub-version show  [--repo-root <path>] [--format text|json]
kub-version check [--repo-root <path>] [--format text|json|github]
kub-version bump  --version <X.Y.Z[-(alpha|beta|rc|preview).N]> | --level <major|minor|patch> [options]

4. Managed Files

kub-version bump updates these files atomically:

  • CMakeLists.txt (project(…​ VERSION …​) and EXTRA_VERSION)

  • pyproject.toml ([project].version)

  • package.json (version)

  • docs/antora.yml (version and asciidoc.attributes.project_version)

  • src/python/feelpp/ktirio/ub/dataset/manifest.py (KUB_VERSION)

  • src/python/feelpp/ktirio/ub/dataset/backends/girder.py (kub_version_min)

  • src/cpp/ktirio/ub/semver.cpp (FEELPP_UB_VERSION_* fallback macros)

5. Commands

5.1. show

Display discovered version values without validating consistency.

kub-version show --repo-root .
kub-version show --repo-root . --format json

5.2. check

Validate consistency between CMake, Python, JavaScript, and C++ fallback versions. Returns exit code 0 on success, 1 on mismatch.

kub-version check --repo-root .
kub-version check --repo-root . --format github

--format github emits ::error::…​ messages for GitHub Actions annotations. check also validates docs/antora.yml against ref context:

  • latest for non-release refs (for example master)

  • vX.Y for refs/heads/vX.Y (and refs/heads/release/vX.Y for compatibility)

  • vX.Y for refs/tags/vX.Y.Z[-pre.N]

5.3. bump

Update all managed version files to a target version. For Antora docs versioning:

  • default bump flow (without --tag) writes docs/antora.yml as latest (development stream)

  • release bump flow with --tag writes docs/antora.yml as vX.Y

  • both flows update docs/antora.yml project_version to X.Y.Z[-pre.N]

  • release bump flow with --tag creates/updates maintenance branch vX.Y only for stable X.Y.0 releases

# explicit target version
kub-version bump --version 0.8.0-rc.1

# automatic bump from current version
kub-version bump --level patch
kub-version bump --level minor
kub-version bump --level major

# automatic prerelease bump
kub-version bump --level patch --pre rc --pre-num 1

5.3.1. bump options

Option Description

`--version <X.Y.Z[-(alpha

beta

rc

preview).N]>`

Set explicit target version (optional leading v accepted). Only alpha, beta, rc, and preview prerelease labels are supported.

`--level <major

minor

patch>`

Compute target automatically from current version.

`--pre <alpha

beta

rc

preview>`

Add prerelease label when using --level.

--pre-num <N>

Prerelease number (default: 1 when --pre is set).

--dry-run

Compute and print target/changed files without writing.

--force

Allow bump with dirty git worktree; also enables forced tag overwrite when tagging.

--commit

Stage only managed version files and create a release commit.

--commit-message <msg>

Custom commit message (default: chore(release): bump version to vX.Y.Z).

--tag

Create annotated git tag after bump (requires --commit). Also writes docs/antora.yml version as vX.Y.

--tag-name <name>

Custom tag name (default: vX.Y.Z).

--tag-message <msg>

Custom tag annotation message (default: Release vX.Y.Z).

--no-branch

With --tag, skip maintenance branch handling/push helper entry.

--branch-name <name>

With --tag, maintenance branch name (default: vX.Y).

6. Version Conventions

KUB uses this split convention:

  • CMake/JS use full release form: X.Y.Z or X.Y.Z-rc.N

  • Python pyproject.toml uses normalized prerelease form: X.Y.ZrcN

  • Antora docs use latest on development bumps and vX.Y for release maintenance lines (typically produced by --tag flow)

Example:

  • CMake/package.json: 0.7.0-rc.2

  • pyproject.toml: 0.7.0rc2

7. Typical Workflows

7.1. Validate current repository state

kub-version check --repo-root .

7.2. Prepare a patch release

kub-version bump --level patch --commit --tag

7.3. Prepare a prerelease candidate

kub-version bump --level patch --pre rc --pre-num 1 --commit --tag

7.4. Preview changes in a dirty tree

kub-version bump --level minor --dry-run

If you need to execute bump operations in a dirty tree, add --force.

8. CI usage

The main CI workflow calls:

python3 -m feelpp.ktirio.release.version_cli check --repo-root "$GITHUB_WORKSPACE" --format github

This makes CI a thin caller of the same logic used locally by maintainers.

9. See Also