Versioning and Releases

Versioning and Releases

OntoKit follows Semantic Versioning (SemVer) with a Weblate-inspired release workflow.

Version Format

MAJOR.MINOR.PATCH[-dev]

Segment	When to bump
MAJOR	Breaking API or schema changes
MINOR	New features, backward-compatible
PATCH	Bug fixes backported to a release line
-dev	Development suffix, stripped at release time

Current version: 0.3.0-dev (development toward the next minor release)

Version Source of Truth

ontokit-api

Version is defined in ontokit/version.py:

VERSION = "0.3.0-dev"          # working version
VERSION_BASE = "0.3.0"         # stripped for PyPI / __version__
TAG_NAME = "ontokit-0.3.0"    # corresponding git tag

pyproject.toml reads the version dynamically via hatch — nothing else to keep in sync.

ontokit-web

Version is defined in package.json:

"version": "0.3.0-dev"

Release Lifecycle

Both ontokit-api and ontokit-web follow the same workflow:

                                                             ┌─ PyPI (API only)
0.2.0-dev ──prepare-release──▸ 0.2.0 ──tag & push──▸ CI ────┼─ GitHub Release
                                                             └─ GHCR Docker image
                                                    │
                                  set-version 0.3.0
                                          │
                                      0.3.0-dev  (next cycle)

Step-by-Step

1. Prepare the release

# API
cd ontokit-api
python scripts/prepare-release.py

# Web
cd ontokit-web
node scripts/prepare-release.mjs

Each script strips the -dev suffix and creates a commit: chore: releasing X.Y.Z.

2. Create a release branch and PR

git checkout -b release/vX.Y.Z
git push -u origin release/vX.Y.Z
gh pr create --title "Release vX.Y.Z" --base main

3. Merge and tag

After review and merge:

git checkout main && git pull
git tag -s ontokit-X.Y.Z        # API tag pattern
git tag -s ontokit-web-X.Y.Z    # Web tag pattern
git push --tags

Tag patterns:

• API: ontokit-* (e.g., ontokit-0.2.0)
• Web: ontokit-web-* (e.g., ontokit-web-0.2.0)

4. CI publishes automatically

When a tag is pushed, GitHub Actions runs lint/test/build and then publishes:

Artifact	API	Web
PyPI	sdist + wheel via trusted publishing	—
GitHub Release	Auto-generated notes + artifacts	Auto-generated notes + artifacts
Docker (GHCR)	ghcr.io/<owner>/ontokit:X.Y.Z	ghcr.io/<owner>/ontokit-web:X.Y.Z

Docker images are tagged with the full version, major.minor, and latest:

• ghcr.io/<owner>/ontokit:0.2.0
• ghcr.io/<owner>/ontokit:0.2
• ghcr.io/<owner>/ontokit:latest

5. Set next development version

# API
python scripts/set-version.py 0.3.0
# Creates commit: "chore: setting version to 0.3.0-dev"

# Web
node scripts/set-version.mjs 0.3.0
# Creates commit: "chore: setting version to 0.3.0-dev"

Push to start the next development cycle.

Patch Releases

Patch releases backport critical bug fixes to an older release line after main has moved on.

For example, if main is at 0.3.0-dev but a bug is found in 0.2.0:

# 1. Branch from the release tag
git checkout -b release/0.2.x ontokit-0.2.0

# 2. Cherry-pick the fix from main
git cherry-pick <commit-sha>

# 3. Bump to patch version in version.py / package.json
#    VERSION = "0.2.1"

# 4. Commit, tag, and push
git commit -m "chore: releasing 0.2.1"
git tag -s ontokit-0.2.1
git push -u origin release/0.2.x && git push --tags

CI publishes the patch release the same way as a minor release. The release/0.2.x branch can be kept for future patches on the same line.

Release History

Version	Date	Highlights
v0.2.0	2025	Suggestion workflow, semantic search, embeddings, quality analysis, analytics, normalization, upstream sync, notifications, join requests, user settings, rate limiting, pre-commit hooks
v0.1.0	2025	Initial release — projects, ontology CRUD, classes, properties, pull requests, linting, search, SPARQL, Git integration, Zitadel auth

Installing a Specific Version

From PyPI

pip install ontokit==0.2.0
# or
uv pip install ontokit==0.2.0

From GHCR

docker pull ghcr.io/<owner>/ontokit:0.2.0

From Source

git checkout ontokit-0.2.0
uv sync --extra dev

Next Steps

• Development — Development workflow
• Configuration — Environment variables reference
• API Reference — API endpoint documentation