Maintenance Guide

This page describes how to perform various maintenance tasks for ccu.

Project and Environment Management

ccu uses hatch for project and environment management. hatch uses the hatchling build system and is configured in the pyproject.toml file.

There are dedicated hatch environments for documentation (docs), code-quality (quality), testing (test), and general development (default) each with their own custom environment scripts. For example, the following command activates the docs environment:

hatch shell docs

GitLab CI/CD

The following jobs are run on all pushed changes and merge requests:

quality

pre-commit hooks: ruff, mypy, formatting & security checks

unit-testing

pytest: unit, functional, and regression tests

doctests

test all doctest examples in documentation

build-docs

sphinx-build: build documentation

linkcheck

check documentation links with the linkcheck builder

The following jobs are only triggered for commits on main:

publish

upload the package to pypi

Release Process

This section walks through the release process.

  1. Determine the version number for the new release.

    • The version number, N is composed of major, minor, and patch components (e.g., in the version number 1.2.3, 1, 2, and 3 are the major, minor, and patch components) with optional pre-release labels

    • While under development, ccu follows a zero-versioning scheme. When stable, ccu releases shall be versioned according to Realistic Semantic Versioning.

    • Pre-releases shall be labeled with “a” and an index, starting from 1 (e.g., 0.0.1a1).

  2. Create a new branch called release-N.

    • For bug fixes, the branch shall be formed from main and eventually separately merged into both main and development.

    • For releases, the branch shall be formed from development and eventually separately merged into both main and development.

  3. Finalize changes. This involves merging any final commits and updating the changelog.

  4. Bump the version using bump-my-version.

    bump-my-version bump --commit VERSION_PART

    where VERSION_PART is one of “major”, “minor”, “patch”, or “pre_n”.

  5. Build the package locally and test upload to test-pypi (optional).

    hatch build
hatch publish -u __token__ -a TOKEN -r test

TOKEN is a valid test-pypi token.

  1. Create and merge a release MR targeting the main branch.

  2. Create a tag on the main branch corresponding to the new version. This will trigger the publish job.