Release Management

This package offers tools to release (tag) Python packages that follow Idiap’s development guidelines. It automatically updates the README.md and pyproject.toml files of the package to setup the correct version and pointers for the release build and documentation badges. The tools are setup to ensure a changelog is provided with each release. The changelog can be autogenerated from merge-requests or commits in the target package.

Usage

Releasing a package is a 2-step process:

  1. Generate a changelog using devtool gitlab changelog.

  2. Create a new GitLab release using devtool gitlab release

Use the --help flag in each command to learn more about each phase.

Warning

Pipelines for stable and non-stable (a.k.a. beta) packages may differ w.r.t. deployment locations for various artefacts (e.g. packages and documentation).

Create the Changelogs

Use the subcommand devtool gitlab changelog <group>/<package> to generate a changelog. Follow examples and instructions at Command-line Interface. Notice this command interacts directly with GitLab and does not require, or use, a local checkout of the package.

You may manually update the output changelog file to edit the proposed releaes notes for the package or packages to be released. This may be extra-important for the part of the (semantic) version number to be bumped, which is indicated on that file. The changelog script cannot guess this and always set “patch” as the part to bump for the next release of the package.

Note

Release numbers

We follow (and advise) one to use Semantic Version numbers. In this scheme, version numbers are composed of 3 parts separated by dots (e.g. “1.2.3”). The first number indicates the major version. The second, the minor version, and, finally, the last number indicates the patch version. Roughly, you should:

  • Bump only the major version if there are breaking API changes

  • Bump only the minor version if there are (backward-compatible) additions to the API

  • Bump only the patch version if the new release only contains bug fixes w/o API changes (additions or removals).

Release the Package

Once the changelog is ready, to release the package, use the command devtool gitlab release. Follow examples and instructions at Command-line Interface. The process is completely automated and documented at that page.