Skip to content

Releasing

This document describes how to create a new release of waldur-site-agent.

Quick Start

1
2
3
./scripts/release.sh 0.10.0
# Review the commit, then push:
git push origin main --tags

The script handles version bumping, changelog generation, committing, and tagging. CI takes care of publishing.

Prerequisites

  • You are on the main branch with a clean working tree.
  • The Claude CLI is installed (used for changelog generation).
  • Python 3.9+ is available.

What the Release Script Does

scripts/release.sh <VERSION> runs four steps:

1. Bump Versions

Calls scripts/bump_versions.py <VERSION>, which auto-discovers all packages and updates:

  • version = "..." in the root pyproject.toml
  • version = "..." in every plugins/*/pyproject.toml
  • Internal dependency pins like waldur-site-agent>=X.Y.Z and waldur-site-agent-keycloak-client>=X.Y.Z

Plugin discovery is automatic — no hardcoded list. Adding a new plugin directory with a pyproject.toml is all that's needed.

2. Generate Changelog

Calls scripts/changelog.sh <VERSION>, which:

  1. Determines the previous version from CHANGELOG.md (or the latest git tag as fallback).
  2. Runs scripts/generate_changelog_data.py to collect commits between the two versions and output structured JSON with categories, stats, and changed files.
  3. Feeds the JSON to Claude with a prompt template (scripts/prompts/changelog-prompt.md) to draft a human-readable changelog entry.
  4. Shows the result and asks you to accept, edit, regenerate, or quit.
  5. Prepends the accepted entry to CHANGELOG.md.

3. Commit

Creates a single commit with the message Release X.Y.Z containing:

  • All updated pyproject.toml files
  • The updated CHANGELOG.md

4. Tag

Creates a git tag X.Y.Z pointing at the release commit.

What Happens After You Push

Pushing the tag to origin triggers GitLab CI, which:

Job What it does
Publish python module Bumps versions, builds, publishes to PyPI
Publish Helm chart Packages chart, pushes to GitHub Pages
Publish Docker image Builds and pushes multiarch images
Generate SBOM Creates CycloneDX SBOM, uploads to docs

Running Individual Scripts

Bump versions only

Update all pyproject.toml files without committing or tagging:

1
python3 scripts/bump_versions.py <VERSION>

Generate changelog only

Generate a changelog entry without bumping versions:

1
scripts/changelog.sh <VERSION>

This is useful if you want to manually edit the changelog before running the full release.

Collect commit data only

Get the raw commit data as JSON (useful for debugging or custom tooling):

1
python3 scripts/generate_changelog_data.py <CURRENT_REF> <PREVIOUS_REF>

Version Scheme

All packages (core + plugins) share the same version number, following MAJOR.MINOR.PATCH (e.g. 0.10.0). Tags do not use a v prefix.

Troubleshooting

"Error: working tree is not clean"

Commit or stash any uncommitted changes before releasing.

"Error: tag 'X.Y.Z' already exists"

The version has already been tagged. Choose a different version number, or delete the tag if it was created by mistake (git tag -d X.Y.Z).

"Error: 'claude' CLI is not on PATH"

The changelog generation step requires the Claude CLI. Install it or generate the changelog manually by editing CHANGELOG.md directly, then run the version bump and commit/tag steps separately:

1
2
3
4
5
python3 scripts/bump_versions.py <VERSION>
# Edit CHANGELOG.md manually
git add pyproject.toml plugins/*/pyproject.toml CHANGELOG.md
git commit -m "Release <VERSION>"
git tag <VERSION>

CI publish job fails

The CI publish job calls bump_versions.py as a safety net before building. If versions are already correct from the release script, this is a no-op. If someone tagged manually without running the release script, CI still stamps the correct versions.