Tagging a New CTA Release¶
All new CTA releases must be tracked by a dev issue with the label
Release (click for link).
These issues must follow the
[Outdated] CTA releases follow the CTA Release Roadmap.
CTA Version Numbering¶
CTA versions are in the format
xis the major version number, which by convention is the same as the XRootD version (
5) which CTA is compiled/linked against.
yis the minor version number, used to indicate that there has been a DB schema upgrade that needs to be properly deployed.
zis the patch version number, used for transparent fixes and unattended upgrades.
ris the release number. Changes in release number means that the code/schema is the same, but there is an update in packaging and/or CI scripts.
All DB schema releases will bump up the minor version number (eg.:
Non-BD schema releases (just code updated) will bump up the patch version number (eg.:
CTA Catalogue Release¶
Any changes to the CTA catalogue schema should have a separate release (only SQL schema changes, no code changes).
These changes (mostly in the submodule
cta-calogue-scema) must be reviewed with the team before being tagged.
These catalogue releases - also refered to as pivot releases - should bump up the minor version number (eg.: from
4.10.0-1), while all the other releases (code releases) should bump up the patch version number (eg.:
In order to guarantee that the catalogue release is consistent with the submodule
cta-calogue-scema, there is a CI script in place that checks for the following pre-requisites:
- Check that
CTA_CATALOGUE_REF_SCHEMA_VERSION_PREV are different.
- Check that there is a migration script from every
- check that the CTA catalogue schema version is the same in both the main CTA project and the
- Check that the 'cta-catalogue-schema' submodule version is tagged.
If needed, the developer in charge of the release can declare a Code Freeze. A Code Freeze begins at a specific date and time (e.g. Wednesday 27 April 2022 at 12:00) and ends when the Release has been tagged. Normally a Code Freeze should last less than one week.
- The Code Freeze should be clearly communicated to the team: at the CTA developer meeting, on the Mattermost
CTA devchannel and on the Release ticket.
- During the Code Freeze, no branches should be merged to
- Exception: bug fixes for regressions uncovered during the stress test can be merged.
However, usually there is no need for a code freeze. Instead, the developer should indicate on the release issue which commit is going to be tagged. The
main branch can then receive new commits after that, which will not be included in the release.
If the tests reveal the need for a fix, it can be done on a separate branch without including any of new commits.
CTA Release Ticket¶
The developer in charge of the release should create a Release issue.
Then, before tagging a release, the developer should:
- Check that all desired feature branches for this Release have been merged to
- Check that all the CI tests are OK. This should include optional tests such as cta_valgrind.
- Check that the Release Notes are up-to-date and contain all of the features, enhancements and bug fixes for this release. In order to guarantee this, please check the merge requests of the new commits. In case of any doubt about any commit, contact directly the creator.
- The Release Notes should also highlight any upgrade issues that operators should be aware of, e.g. if a DB schema upgrade is required.
- Update the CTA version in the Release Notes to the version of this Release.
- Add a summary of the Release to the
- Commit these changes
- Add the commit ID for the release candidate to the issue
In case we need to preserve the
main branch, these last changes can be performed on a separate branch.
cta.spec.in %changelog section¶
The detailed changelog for each Release is in
cta.spec.in %changelog should be a brief summary and should only include important new features, major bug fixes and updates to dependencies. This is a summary
for end-users who will install the RPM.
The text in the
%changelog section of
cta.spec.in is packaged with the RPM and can be viewed with tools like
rpm --changelog and
It has to be formatted in a precise way as the
%changelog is parsed by RPM package management tools. This is the format:
- One line to declare a new Release:
* DoW Mon dd yyyy Firstname Lastname <email@example.com> - vX.Y.Z-R
- Below it, one or more lines short summary of what is in the Release. Each line should start with
-. If the description extends over more than one line (discouraged), the second and subsequent lines should be indented with two spaces. Examples:
- Major feature or new tool Continuation line for very long summaries - Fixes major bug (cta/CTA#1234) - Catalogue schema version X.Y - Updates EOS to vX.Y.Z - Updates XRootD to vX.Y.Z - Updates Ceph to vX.Y.Z
- A single blank line to separate each Release.
The release candidate should be stress tested.
The stress test will be available in a container-based deployment, instructions to follow.
Results from the stress test should be added to the release issue.
Any issues arising from the stress test should be addressed. This will result in a new commit ID.
When the stress test passes, the code should be tagged with the same version mentioned in the Release Notes.
- Normally, tags are created on the git
mainbranch but can also be performed on different branches when we want to isolate them from other commits in
main(eg.: during catalogue/pivot releases).
- Fixes to an already released version of CTA can be tagged in a dedicated branch. Usually this means checking out the tagged version, cherry-picking the commits with the fix, and tagging in the branch. The Code Freeze does not apply in this case.
Follow these steps to tag a release:
- On the Gitlab tags management page, click on New tag.
- Specify the tag name (
- Fill in
Messagewith a short summary of the Release. It is important not to leave this blank, as we want an annotated tag not a lightweight tag. (See git documentation to understand the difference).
- Copy the part of the
ReleaseNotes.mdfile corresponding to the Release vX.Y.Z-R in the
Release notestext area of the GUI. Example:
## Summary This release contains the CTA software Recommended Access Order (RAO) implemented for LTO drives to improve retrieve performances ### Features - CTA software Recommended Access Order (RAO) implemented for LTO drives - Upgraded EOS to 4.8.24-1 - Upgraded xrootd to 4.12.5-1 - cta-admin repack ls tabular output improvements - Repack management execution can be disabled via the cta-taped configuration file - cta/CTA#907 Maintenance process can be disabled via the cta-taped configuration file
- Guarantee that the changelog is updated.
- Click on "Create tag"
Once the Release has been tagged, open a Deployment operations ticket, indicating the tagged version that should be deployed.
After tagging a release, the CI will show an optional state Stage:release_rpm. This trigger the publication of our RPMs in the repos open to the community.
This step should be taken only after our internal release has been approved for production deployment, in order to guarantee that no buggy RPMs are released to the public.