ChristianLempa_Boilerplates/RELEASE.md

Release Process

Overview

Releases are prepared through a release PR and published by pushing a version tag. The GitHub Actions release workflow runs on tags matching v*.*.*.

The release PR should be limited to release preparation changes whenever possible: version files and changelog updates.

Version files

The release version must match in all of these places:

• pyproject.toml
• cli/__init__.py
• Git tag, e.g. vx.x.x

The release workflow validates this and fails if they differ.

Prepare a release

1. Start from an updated main branch.

   git checkout main
   git pull origin main
   git checkout -b release/x.x.x
   

2. Update version files if needed.

   # pyproject.toml
   version = "x.x.x"
   

   # cli/__init__.py
   __version__ = "x.x.x"
   

3. Finalize CHANGELOG.md.

Move entries from:

   ## [Unreleased]

to:

   ## [x.x.x] - YYYY-MM-DD

Then add a fresh empty section above it:

   ## [Unreleased]

1. Run release gates.

   ruff check --fix .
   ruff format .
   python3 -m pytest
   cubic review -j
   

2. Commit and push.

   git add pyproject.toml cli/__init__.py CHANGELOG.md
   git commit -m "release: prepare vx.x.x"
   git push -u origin release/x.x.x
   

3. Open a PR into main.

PR title:

   release: prepare vx.x.x

GitHub Actions automatically runs the configured PR checks for pull requests targeting main. Monitor the PR until those checks complete successfully.

1. Merge the release PR after checks and review pass.

Publish the release

After the release PR is merged:

git checkout main
git pull origin main
git tag vx.x.x
git push origin vx.x.x

Pushing the tag triggers .github/workflows/release-create-cli-release.yaml.

The workflow will:

• validate version consistency
• build the Python package
• run package checks
• create the GitHub Release
• attach .whl and .tar.gz assets
• use the matching changelog section as release notes

Hotfix releases

For hotfix/post releases, use the repository's existing tag format:

vx.x.x-n

The release workflow creates package-compatible asset aliases for these versions.

After release

Verify that:

• the GitHub Release exists
• release assets are attached

• the installer can install the release

  curl -fsSL https://raw.githubusercontent.com/christianlempa/boilerplates/main/scripts/install.sh |
  bash -s -- --version vx.x.x