Releasing

Brief

The goal of this guide is to help you create a new CATs release. Please free to suggest changes based on your experience with this guide.

Release Process

Changes are submitted via PR to the develop branch. Once changes are merged, they are run through the CATs pipeline. Any commit that makes it way through the pipeline is merged up to the release-candidate branch and becomes eligible for release.

Release cadence

Releases are currently published on a best-effort cadence.

Overview

After completing these steps, you will have the following:

1. A published GitHub release with version #.
2. The main branch tagged with release version #.

👉 Please ensure you have write access to this repo. It's required to complete this process.

Step 1

Check for breaking changes.

Special note on versioning

Please read semantic versioning if you're aren't familiar with semantic versioning. A semantic version includes 3 parts - major.minor.patch e.g. 2.1.0. If the new changes aren't compatible with previous versions, then we bump the major version e.g. 2.1.0 => 3.0.0. If the new changes are compatible with the previous versions, then we bump the minor version only e.g. 2.1.0 => 2.2.0. We don't usually bump patch versions.

1. Compare the main branch to the release-candidate candidate branch.
2. Read through each commit and determine if any of them represent breaking changes.

Examples of breaking changes:

• Changed name of, or removed, a test configuration parameter.
• Introduced a change to a test suite that depends upon a recent version of CF-D, CAPI, or the cf CLI.

Commits	Version change	Next step
Have one or more breaking changes	Increments major version e.g.<major+1>.0.0	Follow Major Release section in Step 2
do not have breaking changes	Increments minor version e.g.<major>.<minor+1>.0	Follow Minor Release section in Step 2

Step 2

In this step we will assign a new version # to the release.

Major Release

If there are breaking changes, then,

1. Trigger the ship-it-major job in the CATs pipeline.
2. Click on + on the top right and watch the build execute.
3. Once successfully completed, note down the version # it prints out, e.g. 7.0.0.

⚠️ Major and minor release are mutually exclusive. So if you have completed a major version release, then ignore the Minor Release section below.

Minor Release

If there are no breaking changes, then

1. Trigger the ship-it-minor job in the CATs pipeline.
2. Click on + on the top right and watch the build execute.
3. Once successfully completed, note down the version # it prints out, e.g. 6.8.0.

Step 3

Publish the GitHub release.

1. Navigate to the releases page of this repo.
2. Click the Draft a new release button in the upper right corner of the page.
3. Select the version from Step 2 in the Choose a tag dropdown, and enter that version into Release title, prefixed with a v in both cases.
4. Click the Generate release notes button above the text box.
5. Edit the release notes.
   1. Remove the ## What's Changed header.
   2. Divide the bullet point changes up underneath a ## Breaking Changes header, ## Fixes header, and ## Maintenance header, in that order.
   3. If no changes are divided into a header, then delete that header.
6. Finally, click on the Publish Release button.
7. Post a notice in #cats in the Cloud Foundry Slack workspace. Use the message below to get started and feel free to use emojis!!

     CATs vX has been released.
     Please refer to the release notes for what's changed:
     https://github.com/cloudfoundry/cf-acceptance-tests/releases/tag/vX.0.0
   

Congrats on your release! Go get a cronut with caramel topping!!!