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. 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.

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

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

  7. 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!

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

    • Create a new Tag name:

      • Type the version number (e.g. v1.2.3) in the search bar and click Create tag v1.2.3.

      • Click main and make sure to copy the correct commit in the field Select source! You can do so by copying the SHA (e.g. d187bdb18949dd6eee9463a9ffc99b5ebc38a7d0) of the Release v1.2.3 commit, pasting it into the Select source field and clicking on the commit that pops up.

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

    • 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 ‘#’).

  9. A new CI pipeline is triggered for the new tag. You can find it at the page Code -> Tags by clicking the pipeline indicator that corresponds to release v1.2.3. Take the following steps:

    • After the test and coverage stages have 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 public PyPI repository.

    • Verify that a new version and all corresponding packages have been added to PyPI.

  10. 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 at PyPI. Copy these files into V:\PRJCT\screen\Python\releases\miscore\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\miscore\doc\src. Zip this folder and copy the archive into V:\PRJCT\screen\Python\releases\miscore\doc\zip. Finally, create a shortcut named 1.2.3 to V:\PRJCT\screen\Python\releases\miscore\doc\src\1.2.3\index.html in V:\PRJCT\screen\Python\releases\miscore\doc.

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

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

  12. 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.