Releasing

  1. Ensure the pipeline passed for the last commit on main.

  2. Ensure the wheels can be built for the last commit on main. Click on the two arrows (build stage) next to the two tick marks of the passed pipeline. Now, manually start all the jobs in the build stage.

  3. Ensure all relevant changes are logged in the changelog (doc/changelog.rst).

  4. Evaluate the run time of the example runs by running time_example_runs.py in the main folder. To compare to a previous release, in PyCharm click on your current branch on the bottom right, click “Checkout Tag or Revision”, type the name of the release, and rerun the script.

  5. Create a new branch named e.g. release-1.2.3. Set the release date in the changelog to the current date. In miscore/_version.py, set RELEASED to True. Commit with e.g. the message Release v1.2.3 and push.

  6. Bump the version number in miscore/_version.py. Set RELEASED to False. Commit with the message Bump version number and push.

  7. Open a merge request on GitLab. Make sure the “Squash commits when merge request is accepted” box is unchecked!

  8. Wait until the merge request is approved (preferably today, so that the date in the changelog is correct). When merging, make sure the commits will not be squashed!

  9. On GitLab, create a release with the following properties:

    • Choose the version number (e.g. v1.2.3) as Tag name and Release title.

    • Make sure the correct commit is selected in the field Create from! You can do so by copying the SHA (e.g. d187bdb18949dd6eee9463a9ffc99b5ebc38a7d0) of the Release v1.2.3 commit, pasting it into the Create from field and clicking on the commit that pops up.

    • Select the milestone associated with this release.

    • Add the relevant part of the changelog as release notes. Ensure the formatting is correct by checking the Preview (titles must be preceded by a ‘#’).

  10. A new CI pipeline is triggered for the new tag. Take the following steps:

    • After the test stage has finished, manually start all the jobs in the build stage. This will build all the binary wheels, as well as the source distribution.

    • After the build stage has finished, manually start the release job. This will upload all files created in the build stage to the GitLab PyPI repository.

    • Verify that a new package has been added to the Package Registry.

  11. Archive all binary wheels, the source distribution, documentation and the entire project source in V:\PRJCT\screen\Python\releases.

    • The binary wheels (.whl) and source distribution (.tar.gz) can all be found in the Package Registry. Copy these files into V:\PRJCT\screen\Python\releases\whl.

    • The documentation can be retrieved by downloading the job artifact of the test_documentation job of the pipeline triggered by the created tag. Extract the archive, rename the html folder to e.g. 1.2.3 and copy this folder into V:\PRJCT\screen\Python\releases\doc\src. Zip this folder and copy the archive into V:\PRJCT\screen\Python\releases\doc\zip. Finally, create a shortcut named 1.2.3 to V:\PRJCT\screen\Python\releases\doc\src\1.2.3\index.html in V:\PRJCT\screen\Python\releases\doc.

    • Download the source code in .zip format on the release page. Copy this archive into V:\PRJCT\screen\Python\releases\src.

  12. Close the milestone. Move any open issues and merge requests to the next milestone.

  13. Let people know (e.g. by mail or Teams) about the new release!

Changelog

All significant changes should be logged in the changelog. For each new version, we add a section to Changelog. Each section contains a subsection on core, utils, processes, tools (e.g. CEA and calibration tools), utils, tests (the pipeline) and others.

Versioning

Version numbers should follow PEP440 and the Semantic Versioning scheme.