Skip to content

Versioning and Releases

Semver strategy, conventional commits, and release procedures for all CWIQ services.

Version Strategy by Artifact Type

Platform Services (Docker Images)

Platform services (server, ui, agent, microservices) are versioned via git tags on each sub-repository. The CI/CD pipeline:

  1. Builds the Docker image and saves the tag in build.env as IMAGE_TAG
  2. The deploy stage consumes IMAGE_TAG from build.env
  3. Branch builds produce main-{sha} tags — these are not released and not semantically versioned
  4. A version tag (v1.2.3) on the repo triggers the release stage, which creates a GitLab release and tags the image as 1.2.3 + stable

Executor CLI (RPM-packaged)

Property Value
Version source executor/pyproject.toml (version field)
Format {major}.{minor}.{patch} (semver)
RPM release field 0.dev for development builds
RPM dist macro %{?dist} only — do NOT add .${DIST} in rpmbuild --define (causes double suffix)
Tag format for releases v{major}.{minor}.{patch} (e.g., v0.3.0)

cwiq-common Shared Library (PyPI)

  • Current version: 0.2.0
  • Hosted at Nexus PyPI: https://nexus.shared.cwiq.io/repository/pypi-hosted/
  • Installed via: https://nexus.shared.cwiq.io/repository/pypi-group/simple/

Conventional Commits

CWIQ follows the Conventional Commits specification.

Commit Type Version Bump Example
feat: MINOR feat(search): add global search endpoint
fix: PATCH fix(auth): handle token expiry correctly
feat!: or BREAKING CHANGE: MAJOR feat!: remove deprecated v1 endpoints
chore: No bump chore: update dependencies
docs: No bump docs: update API reference
ci: No bump ci: fix deploy stage SSH key handling
refactor: No bump refactor(workflow): split domain module

Breaking changes

A breaking change can appear on any commit type by adding ! after the type or including BREAKING CHANGE: in the commit footer. Either triggers a MAJOR version bump.

Release Tag Format

All releases use the v prefix:

git tag -a v1.2.3 -m "Release v1.2.3 - brief summary"
git push origin v1.2.3

This triggers: - The release CI stage (creates GitLab release with notes) - Docker image tagged as 1.2.3 and stable - For executor: RPM built with version from pyproject.toml, uploaded to Nexus yum-hosted-dev

GitLab Release Job Trigger

# The release stage fires only on version tags
rules:
  - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+/'

Checking What Changed Since Last Release

# List commits since the last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

# Or check the latest tag
git describe --tags --abbrev=0