Release instructions

This document outlines the steps required to create a new release of the project.

Prerequisites

1. Pick a new version number. We follow Calendar Versioning in the format YY.WW.MICRO.

   • For the first release of the week, use YY.WW.0 (e.g. 26.5.0 for the release in the 5th week of 2026).

   • For subsequent releases in the same week, increment the MICRO version (e.g. 26.5.1, 26.5.2, etc.).

   • The week number should not be zero-padded to two digits, e.g. 5, 12, etc.

   In general, do not create releases of alpha, beta, or release candidate versions (e.g. 26.5.0a1, 26.5.1b2, 26.5.1rc3)! If you know what you are doing, you can push a tag of such a version, but never create a release in Gitlab for it.

2. Ensure that you are at least a Maintainer on the project to have permission to create protected tags and merge into main.

Creating the release

1. Create a new branch from the main branch named release-x.y.z, where x.y.z is the new version number.

2. In this branch, update the CHANGELOG.md file with the changes included in this release. Write a short summary of the release, and include a list of all commits since the last release. Below is the template to use for the changelog entry:

   ## vx.y.z (DD.MM.YYYY)
   
   {short summary of the release}
   
   ### Full release notes
   
   - {commit message 1}
   - {commit message 2}
   - ... etc. ...
   

3. Commit the changes and open a MR called chore: update changelog for vx.y.z release to merge the changes back into the main branch. Request a review and wait for approval.

4. Once the MR is merged and the pipeline on main has completed successfully, create a new tag for the release from the Gitlab UI by clicking “New tag”. In the “Tag name” field, enter vx.y.z. For the branch, select main. In the “Message” field, copy the changelog entry created above. Finally, create the tag.

5. Wait for the pipeline for the new tag to complete successfully. The pipeline releases the new version in three locations:

   • The Python package (.whl) is pushed to the local GitLab package registry.

   • The RPM package (.rpm) is pushed to the local GitLab package registry.

   • The documentation is pushed to https://docs.orangeqs.com/juice/core/.

6. Once the pipeline of the new tag has completed successfully, create a new release from the Gitlab UI by clicking “Create release” on the tag you just created. Creating a release in Gitlab is purely cosmetic and provides a nice UI for users to see the release notes. Leave the release title blank such that the tag name is used. Check “Include message from the annotated tag” to include the changelog entry in the release notes. Finally, create the release.

7. Announce the new release in the appropriate channels.

   • Post in the #product-orangeqs-juice-os channel on Slack.

   • Post in the Official Updates category under the subcategory Release Notes on the discource community

   • Post in the #orangeqs-juice channel on the Unitary Fund Discord server.

   Use the following template for the announcement:

   ✨ A new version of OrangeQS Juice is now available!
   
   
   ```
   {copy the changelog entry here}
   ```