Tagging a New CTA Release¶

CTA Releases¶

All new CTA releases must be tracked by a dev issue with the label Release (click for link).

These issues must follow the Release template.

[Outdated] CTA releases follow the CTA Release Roadmap.

CTA Version Numbering¶

CTA versions are in the format x.y.z-r.

x is the major version number, which by convention is the same as the XRootD version (4 or 5) which CTA is compiled/linked against.
y is the minor version number, used to indicate that there has been a DB schema upgrade that needs to be properly deployed.
z is the patch version number, used for transparent fixes and unattended upgrades.
r is 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.: 4.10.0-1). Non-BD schema releases (just code updated) will bump up the patch version number (eg.: 4.10.1-1).

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.9.0-1 to 4.10.0-1), while all the other releases (code releases) should bump up the patch version number (eg.: 4.10.1-1).

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_CURR and CTA_CATALOGUE_REF_SCHEMA_VERSION_PREV are different. - Check that there is a migration script from every CTA_CATALOGUE_REF_SCHEMA_VERSION_PREV to CTA_CATALOGUE_REF_SCHEMA_VERSION_CURR. - check that the CTA catalogue schema version is the same in both the main CTA project and the cta-catalogue-schema submodule. - Check that the 'cta-catalogue-schema' submodule version is tagged.

Code Freeze¶

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 dev channel and on the Release ticket.
During the Code Freeze, no branches should be merged to main.
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 main.
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 %changelog section of cta.spec.in (see below)
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 ReleaseNotes.md.

The 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 repoquery --changelog. 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 <firstname.lastname@cern.ch> - 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.

Stress Test¶

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.

Tagging¶

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 main branch 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 (vX.Y.Z-R)
Fill in Message with 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.md file corresponding to the Release vX.Y.Z-R in the Release notes text 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"

Deployment¶

Once the Release has been tagged, open a Deployment operations ticket, indicating the tagged version that should be deployed.

Public release¶

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.