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:
Generate a changelog using
devtool gitlab changelog
.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.