site-content/source/modules/ROOT/pages/development/release_process.adoc

:page-layout: basic

== 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::
  * http://www.apache.org/legal/release-policy.html[ASF Release Policy]
  * http://www.apache.org/dev/release-distribution[ASF Release
  Distribution Policy]
  * https://infra.apache.org/release-publishing.html[ASF Release
  Best Practices]

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
http://www.apache.org/dev/openpgp.html[guidelines]. **The key must be 4096
bit RSA.**

Publish your GPG key in a PGP key server, such as
http://pgp.mit.edu/[MIT Keyserver]. Some `gpg` clients are publishing the keys https://keys.openpgp.org/[here]. You are 
welcome to set the server where the keys will be published by following https://keys.openpgp.org/about/usage[this guide].

Once completed, you need to create a ticket https://issues.apache.org/jira/browse/CASSANDRA-18205[like this] 
and ask a PMC to add your key to `KEYS` file.

A PMC will include your public key to this file:

[source,none]
----
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 https://packages.debian.org/bullseye/createrepo-c[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:

[source,none]
----
cd ~/git
git clone https://github.com/apache/cassandra-builds.git
git clone https://github.com/apache/cassandra.git
----

[source,none]
----
# Edit the variables at the top of the `prepare_release.sh` file
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:

[source,none]
----
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.

[source,none]
----
# Ensure your 4096 RSA key is the default secret key
edit ~/.gnupg/gpg.conf # update the `default-key` line
----

A reference configuration should look like these examples:

[source,none]
----
default-key <fingerprint of your key>
personal-digest-preferences SHA512
cert-digest-algo SHA512
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
----

[source,none]
----
edit ~/.rpmmacros # update the `%_gpg_name <key_id>` line
# Ensure DEBFULLNAME and DEBEMAIL is defined and exported, in the debian scripts configuration
edit ~/.devscripts
----

The reference content of these files is:

[source,none]
----
$ cat ~/.rpmmacros 
%_gpg_name email@youusedforyourkey.org
$ cat ~/.devscripts 
DEBFULLNAME="Your Name"
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 https://repository.apache.org/[staging repository]. The credentials are your ASF credentials.

[source,none]
----
$ cat ~/.m2/settings.xml 
<settings>
    <servers>
        <server>
            <id>apache.releases.https</id>
            <username>yourasflogin</username>
            <password>yourasfpassword</password>
        </server>
        <server>
            <id>apache.snapshots.https</id>
            <username>yourasflogin</username>
            <password>yourasfpassword</password>
        </server>
    </servers>
</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.

[source,none]
----
cd cassandra
git switch cassandra-<version-branch>

# The following cuts the release artifacts (including deb and rpm packages) and deploy to staging environments
../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
https://repository.apache.org/#stagingRepositories[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 [.title-ref]#-d# and [.title-ref]#-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:

[source,none]
----
I propose the following artifacts for release as <version>.

sha1: <git-sha>

Git: https://gitbox.apache.org/repos/asf?p=cassandra.git;a=shortlog;h=refs/tags/<version>-tentative

Artifacts: https://repository.apache.org/content/repositories/orgapachecassandra-<nexus-id>/org/apache/cassandra/apache-cassandra/<version>/

Staging repository: https://repository.apache.org/content/repositories/orgapachecassandra-<nexus-id>/

The distribution packages are available here: https://dist.apache.org/repos/dist/dev/cassandra/${version}/

The vote will be open for 72 hours (longer if needed).

[1]: (CHANGES.txt) https://git1-us-west.apache.org/repos/asf?p=cassandra.git;a=blob_plain;f=CHANGES.txt;hb=<version>-tentative
[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:

[source,none]
----
cd ~/git
# edit the variables at the top of the `finish_release.sh` file
edit cassandra-builds/cassandra-release/finish_release.sh

# After cloning cassandra-builds repo, `finish_release.sh` is run from the actual cassandra git checkout,
# on the tentative release tag that we wish to tag for the final release version number tag.
cd ~/git/cassandra/
git checkout <version>-tentative
../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 https://repository.apache.org[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 https://svn.apache.org/repos/asf/cassandra/site/src/README[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:

[source,none]
----
cd ~/git/cassandra/
git checkout cassandra-<version-branch>
edit build.xml          # update `<property name="base.version" value="…"/> `
edit debian/changelog   # add entry for new version
edit CHANGES.txt        # add entry for new version
git commit -m "Increment version to <next-version>" build.xml debian/changelog CHANGES.txt

# …and forward merge and push per normal procedure
----

=== Wait for Artifacts to Sync

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

=== Send Release Announcement

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

[source,none]
----
The Cassandra team is pleased to announce the release of Apache Cassandra version <version>.

Apache Cassandra is a fully distributed database. It is the right choice
when you need scalability and high availability without compromising
performance.

 http://cassandra.apache.org/

Downloads of source and binary distributions are listed in our download
section:

 http://cassandra.apache.org/download/

This version is <the first|a bug fix> release[1] on the <version-base> series. As always,
please pay attention to the release notes[2] and let us know[3] if you
were to encounter any problem.

Enjoy!

[1]: (CHANGES.txt) https://git1-us-west.apache.org/repos/asf?p=cassandra.git;a=blob_plain;f=CHANGES.txt;hb=<version>
[2]: (NEWS.txt) https://git1-us-west.apache.org/repos/asf?p=cassandra.git;a=blob_plain;f=NEWS.txt;hb=<version>
[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
http://www.apache.org/dev/release.html#when-to-archive[When to Archive].

An example of removing old releases:

[source,none]
----
svn co https://dist.apache.org/repos/dist/release/cassandra/ cassandra-dist
svn rm <previous_version> debian/pool/main/c/cassandra/<previous_version>*
svn st
# check and commit
----