Release Management

This package offers tools to release (tag) packages that follow Bob’s development guidelines. It automatically updates the README.rst and version.txt 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.

Warning

Releasing any package that is listed in the nightlies repository requires a green nightlies after all changes have been merged to the master branches of all packages. Do not release a package because it is green by itself. Its compatibility must be tested against all other packages first.

Usage

Releasing Bob is a 4-step process:

  1. Generate a changelog using bdt gitlab changelog. * remove bob/bob from the changelog if it is present.

  2. Tag a release using bdt gitlab release

  3. Release bob/bob manually.

  4. Release bob/docs manually.

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

Note

If the package that you are releasing is not part of the nightlies repository, you can skip steps 3 and 4.

Warning

While beta builds of packages will use the beta version of this package, stable will look for the latest stable version of this package for their build configuration.

To correctly produce a release, ensure a STABLE version of bob.devtools is properly released before you start tagging packages. The builds will then use such version of this package to enforce the correct build environment during the packaging.

If you forget to properly tag this package before doing so you risk building against the wrong set of dependencies.

Generate the Changelog

After generating a changelog.md file using the bdt gitlab changelog command, you must edit the file manually. The structure of the file is documented as part of the help message of bdt gitlab release. Read it.

To manually update the changelog, follow these guidelines:

  1. For each tag, summarize the commits into several descriptive lines. These summaries become tag descriptions and they should extend/update the existing tag description. Therefore, each line of the summary should also start with * character like the tag descriptions.

  2. The last tag name is called patch. This indicates that a patch version of this package will be automatically updated during the next tag/release. You can change patch to minor or major, and the package will be then tagged/released with either minor or major version bump. You may also set an explicit tag to the package (e.g. v1.0.0), which may be required if no tags are available yet on gitlab.

  3. Once all commits were changed to corresponding tag descriptions (no more lines start with - characters), this package is ready for release and you can continue to another package in the changelog.

Note

Remove the bob/bob line and its associated lines from the changelog if it is present. This package must be released manually.

Warning

Identifying the correct version of each package is important. We follow semantic versioning (see https://semver.org/). Even if there are small breaking changes in the package, we should always bump the major version. Our conda packages rely on that.

Release the Package(s)

Use the bdt gitlab release command to tag the release of each package. This process is automatic but will take a long time to finish.

Releasing the Bob meta package

Here are the instructions to release Bob meta package:

  • Run:

    $ cd bob
$ bdt gitlab update-bob -vvv --stable

  • The script above cannot identify linux only packages. After running the script, you need to manually tag linux only packages in conda/meta.yaml. For example:

    - bob.ip.binseg ==1.1.0  # [linux]
- bob.bio.face ==7.0.0  # [not arm64]

    Use git diff to make sure you have preserved the comments.

  • Test the conda recipe of bob. You may want to cancel the command below once it reaches the unit tests:

    $ bdt build -vv --stable

  • Commit the changes and push:

    $ git commit -m "Pinning packages for the next release. [skip ci]" conda/meta.yaml requirements.txt
$ git push

  • Tag the package using the same changelog mechanism that you used to tag other packages. Assuming the changelog has a * bob/bob entry:

    $ bdt gitlab release -vvv changelog.md --package bob/bob

  • When the script says Waiting for the pipeline *** of "bob/bob" to finish, you may cancel it and check the progress online.

  • You must revert the pins while in beta run:

    $ git pull --rebase
$ bdt gitlab update-bob -vvv --beta

  • Like before, tag the linux only or intel only packages manually and make sure to preserve the comments.

  • Commit and push the changes:

    $ git commit -m "Remove package pins while in beta. [skip ci]" conda/meta.yaml requirements.txt
$ git push

You can see that if we could have preserved the comments automatically, the whole release process would have been only to run bdt gitlab release -vvv changelog.md --package bob/bob given that we call bdt gitlab update-bob inside that command. Do you want to help fix that?

Release the docs meta package

Don’t forget to release bob/docs after the bob release has successfully finished. To do so, just go to https://gitlab.idiap.ch/bob/docs/-/tags and click on New tag. Use the same version number you used for bob/bob.