Release Process

The steps for Release Managers to create, vote, and publish releases for Apache Cassandra.

While a committer can perform the initial steps of creating and calling a vote on a proposed release, only a PMC member can complete the process of publishing and announcing the release.

Prerequisites

Background docs

A debian based linux OS is required to run the release steps from. Debian-based distros provide the required RPM, dpkg and repository management tools.

Create and publish your GPG key

To create a GPG key, follow the guidelines. The key must be 4096 bit RSA.

Publish your GPG key in a PGP key server, such as MIT Keyserver. Some gpg clients are publishing the keys here. You are welcome to set the server where the keys will be published by following this guide.

Once completed, you need to create a ticket like this and ask a PMC to add your key to KEYS file.

A PMC will include your public key to this file:

  1. https://dist.apache.org/repos/dist/release/cassandra/KEYS

Create Release Artifacts

Any committer can perform the following steps to create and call a vote on a proposed release.

Check that there are no open urgent Jira tickets currently being worked on. Also check with the PMC that there’s security vulnerabilities currently being worked on in private. Current project habit is to check the timing for a new release on the dev mailing lists.

For successful building process, install this tooling locally: svn, git, ant, devscripts, reprepro, rpmsign, docker, createrepo (the script is checking this tooling is present before proceeding any further). The names of these “packages” are Debian-centric, but equivalents should be discoverable in other systems too.

There is a package called createrepo-c in Debian Bullseye. Please beware that createrepo package is not located in Ubuntu 20.04 LTS. createrepo package is present in Ubuntu Bionic (18.04), createrepo-c is in Ubuntu Jammy (22.04 LTS) and more recent.

Perform the Release

Run the following commands to generate and upload release artifacts, to the ASF nexus staging repository and dev distribution location:

  1. cd ~/git
  2. git clone https://github.com/apache/cassandra-builds.git
  3. git clone https://github.com/apache/cassandra.git
  1. # Edit the variables at the top of the `prepare_release.sh` file
  2. edit cassandra-builds/cassandra-release/prepare_release.sh

You must specify your ASF username to asf_username variable. Next, gpg_key environment variable must be set to a fingerprint of your gpg key. Execute gpg --list-keys or a similar command to get the value. Finally, you must add ASF remote to your cloned repository and git_asf_remote variable needs to be set to point to that. For example, when this command is executed:

  1. git remote add asf https://gitbox.apache.org/repos/asf/cassandra.git

then git_asf_remote variable needs to be set to asf. NOTE: This is very important step as tags are pushed to ASF repository and they are synchronized to GitHub automatically.

  1. # Ensure your 4096 RSA key is the default secret key
  2. edit ~/.gnupg/gpg.conf # update the `default-key` line

A reference configuration should look like these examples:

  1. default-key <fingerprint of your key>
  2. personal-digest-preferences SHA512
  3. cert-digest-algo SHA512
  4. default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
  1. edit ~/.rpmmacros # update the `%_gpg_name <key_id>` line
  2. # Ensure DEBFULLNAME and DEBEMAIL is defined and exported, in the debian scripts configuration
  3. edit ~/.devscripts

The reference content of these files is:

  1. $ cat ~/.rpmmacros
  2. %_gpg_name email@youusedforyourkey.org
  3. $ cat ~/.devscripts
  4. DEBFULLNAME="Your Name"
  5. DEBEMAIL=email@youusedforyourkey.org

Empirical testing shows that you also must have the above DEB* environemnt variables exported before proceeding.

Additionally, you must configure $HOME/.m2/settings.xml to contain the credentials used to upload artifacts to staging repository. The credentials are your ASF credentials.

  1. $ cat ~/.m2/settings.xml
  2. <settings>
  3.     <servers>
  4.         <server>
  5.             <id>apache.releases.https</id>
  6.             <username>yourasflogin</username>
  7.             <password>yourasfpassword</password>
  8.         </server>
  9.         <server>
  10.             <id>apache.snapshots.https</id>
  11.             <username>yourasflogin</username>
  12.             <password>yourasfpassword</password>
  13.         </server>
  14.     </servers>
  15. </settings>

The script will eventually ask you for a username and password to push artifacts to SVN. The default prompt for user will be equal to a username of an account at your machine. If your ASF login is not same as your username locally, just error out the prompt (put there wrong password and confirm), and it will ask you for username again without providing any default value.

The prepare_release.sh is run from the actual cassandra git checkout, on the branch/commit that we wish to tag for the tentative release along with version number to tag.

  1. cd cassandra
  2. git switch cassandra-<version-branch>
  4. # The following cuts the release artifacts (including deb and rpm packages) and deploy to staging environments
  5. ../cassandra-builds/cassandra-release/prepare_release.sh -v <version>

Follow the prompts.

Once artifacts are built and pushed to the staging area, the script will pause and require you to go to the Staging repositories, where you will find the repository. Select the Cassandra repository and push the “Close” button. Please take a note of the number of that repository like orgapachecassandra-1283 - number is 1283. The script will require the repo number to proceed. It will use this number in the rendered e-mail template sent to the dev list, etc.

If building the deb or rpm packages fail, those steps can be repeated individually using the -d and -r flags, respectively.

Once DEBs and RPMs are also uploaded, do not forget to merge your commit to prepare the release to trunk and push after all artifacts are uploaded finish the process. You will be also reminded to do that by the script itself at the end.

Call for a Vote

Fill out the following email template you find in $HOME/Mail directory and send to the dev mailing list:

  1. I propose the following artifacts for release as <version>.
  3. sha1: <git-sha>
  5. Git: https://gitbox.apache.org/repos/asf?p=cassandra.git;a=shortlog;h=refs/tags/<version>-tentative
  7. Artifacts: https://repository.apache.org/content/repositories/orgapachecassandra-<nexus-id>/org/apache/cassandra/apache-cassandra/<version>/
  9. Staging repository: https://repository.apache.org/content/repositories/orgapachecassandra-<nexus-id>/
  11. The distribution packages are available here: https://dist.apache.org/repos/dist/dev/cassandra/${version}/
  13. The vote will be open for 72 hours (longer if needed).
  15. [1]: (CHANGES.txt) https://git1-us-west.apache.org/repos/asf?p=cassandra.git;a=blob_plain;f=CHANGES.txt;hb=<version>-tentative
  16. [2]: (NEWS.txt) https://git1-us-west.apache.org/repos/asf?p=cassandra.git;a=blob_plain;f=NEWS.txt;hb=<version>-tentative

Post-vote operations

Any PMC member can perform the following steps to formalize and publish a successfully voted release.

Publish Artifacts

Run the following commands to publish the voted release artifacts:

  1. cd ~/git
  2. # edit the variables at the top of the `finish_release.sh` file
  3. edit cassandra-builds/cassandra-release/finish_release.sh
  5. # After cloning cassandra-builds repo, `finish_release.sh` is run from the actual cassandra git checkout,
  6. # on the tentative release tag that we wish to tag for the final release version number tag.
  7. cd ~/git/cassandra/
  8. git checkout <version>-tentative
  9. ../cassandra-builds/cassandra-release/finish_release.sh -v <version>

If successful, take note of the email text output which can be used in the next section “Send Release Announcement”. The output will also list the next steps that are required.

Promote Nexus Repository

  • Login to Nexus repository again.

  • Click on “Staging Repositories” and then on the repository with id “cassandra-staging”.

  • Find your closed staging repository, select it and choose “Release”. This may take some time, but eventually the repository will no longer show in Staging Repositories.

  • Next click on “Repositories”, and select “Public Repositories” and validate that your artifacts exist as you expect them.

Update and Publish Website

See docs for building and publishing the website.

Also update the CQL doc if appropriate.

Release version in JIRA

Release the JIRA version.

  • In JIRA go to the version that you want to release and release it.

  • Create a new version, if it has not been done before.

Update to Next Development Version

Update the codebase to point to the next development version:

  1. cd ~/git/cassandra/
  2. git checkout cassandra-<version-branch>
  3. edit build.xml          # update `<property name="base.version" value="…"/> `
  4. edit debian/changelog   # add entry for new version
  5. edit CHANGES.txt        # add entry for new version
  6. git commit -m "Increment version to <next-version>" build.xml debian/changelog CHANGES.txt
  8. # …and forward merge and push per normal procedure

Wait for Artifacts to Sync

Wait for the artifacts to sync at downloads.apache.org/cassandra/

Send Release Announcement

Fill out the following email template and send to both user and dev mailing lists:

  1. The Cassandra team is pleased to announce the release of Apache Cassandra version <version>.
  3. Apache Cassandra is a fully distributed database. It is the right choice
  4. when you need scalability and high availability without compromising
  5. performance.
  7.  http://cassandra.apache.org/
  9. Downloads of source and binary distributions are listed in our download
  10. section:
  12.  http://cassandra.apache.org/download/
  14. This version is <the first|a bug fix> release[1] on the <version-base> series. As always,
  15. please pay attention to the release notes[2] and let us know[3] if you
  16. were to encounter any problem.
  18. Enjoy!
  20. [1]: (CHANGES.txt) https://git1-us-west.apache.org/repos/asf?p=cassandra.git;a=blob_plain;f=CHANGES.txt;hb=<version>
  21. [2]: (NEWS.txt) https://git1-us-west.apache.org/repos/asf?p=cassandra.git;a=blob_plain;f=NEWS.txt;hb=<version>
  22. [3]: https://issues.apache.org/jira/browse/CASSANDRA

Update Slack Cassandra topic —————————————-

Update topic in cassandra Slack room <slack>

/topic cassandra.apache.org | Latest releases: 4.1.0, 4.0.7, 3.11.4, 3.0.18 | ask, don’t ask to ask

Tweet from @Cassandra

Tweet the new release, from the @Cassandra account

Delete Old Releases

As described in When to Archive.

An example of removing old releases:

  1. svn co https://dist.apache.org/repos/dist/release/cassandra/ cassandra-dist
  2. svn rm <previous_version> debian/pool/main/c/cassandra/<previous_version>*
  3. svn st
  4. # check and commit