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.

Preparing the MR for release:#

  1. Prepare the changelog MR by using one of the following workflows.

    1. Trigger the Generate Changelog MR for Weekly Release job. In the weekly process, this is done by a scheduled pipeline. For an out-of-band release, run a pipeline manually on main and then trigger this manual job.

    2. Wait for the job to complete. It will open a new MR for the release.

    3. Review the generated changelog entry in the MR. Update it directly in the MR if needed. Ensure the summary is correct and that commit notes look complete. Make sure to update the descriptions to be human readable, this is the responsibility of the maintainer.

    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 your release-x.y.z branch, update CHANGELOG.md with the changes included in this release. Write a short summary of the release. Include a list of all commits since the last release. Use this template:

      ## vx.y.z (DD.MM.YYYY)

{short summary of the release}

### Full release notes

- {commit message 1}
- {commit message 2}
- ... etc. ...

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

    Scripting Changelog Generation

    Even for manual releases, you can use the scripts in tooling/ to generate draft content. See tooling/README.md for more details.

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

  3. Wait for the pipeline for the new tag to complete successfully. The pipeline releases the new version in the following 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 DEB package (.deb) is pushed to the local GitLab package registry.

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

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

  5. Announce the new release in the appropriate channels.

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

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

    Use the following template for the announcement(remember to insert the version in the link to the installation guide).

    ✨ A new version of OrangeQS Juice is now available!
## Useful Links
- [Source Code (GitLab)](https://gitlab.com/orangeqs/juice)
- [Installation Guide](https://docs.orangeqs.com/juice/core/<INSERT_VERSION>/tutorials/getting-started/installation.html)

```
{copy the changelog entry here}
```

    You can also auto-generate this locally by running:

    tooling/changelog_tool.py --release-announcement