This article contains all the steps required to release Apache Geode. 

Before you begin

Software dependencies

1. git →  https://git-scm.com/downloads
2. docker → https://docs.docker.com/docker-for-mac/install/ 
3. svn → [on Mac, install command line tools → https://stackoverflow.com/questions/9329243/xcode-install-command-line-tools]
4. gpg tools → https://gpgtools.org
5. java JDK8 → https://adoptopenjdk.net
6. Homebrew (optional) → https://brew.sh/
7. fly → use platform-appropriate download link in bottom right corner of https://concourse.apachegeode-ci.info
8. cmake, doxygen, and openssl - install using an appropriate package manager, e.g. on Mac: brew install doxygen && brew install cmake && brew install openssl
9. text editor (vi or whatever you prefer)
10. web browser

Permission and keys

Announce intent to branch

Geode cuts release branches on a time-based schedule (Monday on or after Feb 1, May 1, Aug 1, Nov 1).  About a week before, send a [DISCUSS] email to dev@geode.apache.org informing developers that a new release branch is about to be created.  Remind the community that only critical fixes will be allowed once the release branch is created, so it is helpful to have develop as stable as possible before branching.

Also ask the community to confirm that the Geode LICENSE and NOTICE files accurately reflect what is on develop. 

Branching for release

Create the release branch

1. Check for the most recent develop SHA that passes all the tests and contains all the features / bug fixes that need to go into the release at https://concourse.apachegeode-ci.info/teams/main/pipelines/apache-develop-main/jobs/UpdatePassingTokens.
2. Ensure that all JIRA tickets mentioned in commits (since the last release branch was cut) are marked as Resolved in JIRA.  If not, ask assignees if there is still more work to be done.
3. Ensure in JIRA, that all tickets with {version} as the fix version are either closed or resolved. If not inform the the assignees to either mark it Resolved or  increment the fix version.

4. Create the release branch (from HEAD should be fine, or if necessary you can specify a particular SHA, such as the last commit that passed the develop pipeline successfully)

   git checkout develop
   git checkout -b release/{version} [GOOD_SHA]

5. Update the version number in gradle.properties (and remove -SNAPSHOT)

6. Update the version number in ci/pipelines/geode-build/jinja.template.yml

7. Change SNAPSHOT to "" for SEMVER_PRERELEASE_TOKEN in ci/pipelines/meta/meta.properties

8. Update the version number in all the expected pom files:

   ./gradlew clean
   ./gradlew build -Dskip.tests=true #note: ok if build fails expected pom test
   ./gradlew updateExpectedPom

    

9. Review the benchmark baseline.  It should be the more recent of {previous release} or develop/highwater.  branch should stay as develop even for release branches.  Note: as the release progresses, consider creating and using a dedicated version/highwater tag on the release branch.

   See ci/pipelines/shared/jinja.variables.yml around line 19:

    benchmarks:
      baseline_branch: develop/highwater
      baseline_version: ''
      benchmark_branch: develop

10. Publish the release branch to origin

    git add .
    git commit -a -m "Upgraded version number for releasing {version}"
    git push origin HEAD

11. Now checkout the repo for geode-examples (apache/geode-examples.git) and create a release branch.

    git clone git@github.com:apache/geode-examples.git
    git checkout develop origin/develop
    git checkout -b release/{version}

12. Update the version number in gradle.properties of geode-examples and remove -SNAPSHOT

    version = 1.7.0
    geodeVersion = 1.7.0

13. Commit the version changes and push the release branch of geode-examples

    git add -p
    git commit
    git push origin HEAD

14. Checkout the repo for geode-native (apache/geode-native.git) and create a release branch

    git checkout develop
    git checkout -b release/{version}
    git push origin HEAD

15. Send email to dev@geode.apache.org informing the creation of the release branch and requesting feedback.

    Hello Geode Dev Community,
    
    We have created a new release branch for Apache Geode {version} - "release/{version}"
    
    Please do review and raise any concern with the release branch.
    If no concerns are raised, we will start with the voting for the release candidate soon.
    
    Regards
    {Release Manager}

16. Create the concourse release pipeline.

    fly -t concourse.apachegeode-ci.info login --concourse-url https://concourse.apachegeode-ci.info/
    cd ci/pipelines/meta
    ./deploy_meta.sh

17. Monitor the new release pipeline and resolve any issues that may arise. 

Begin preparing release documentation

1. Start preparing the release docs at Release Notes. Use information from all the JIRAs that were closed or resolved. 

2. Also write up a short paragraph on what was added to the release. This will need to go with the final announce email. Sample:

   Geode 1.7.0 contains a number of improvements and bug fixes.
   It includes performance improvements in OQL order-by and distinct queries in client/server when security is enabled.
   New GFSH commands were added to get/set cluster config and to destroy gateway receivers. A new post processor was 
   added to the new client protocol. Pulse now supports legacy SSL options. Auto-reconnecting members no more reuse 
   old addresses and IDs. Duplicated or member-specific receivers are removed from cluster config during rolling upgrades.
   Users are encouraged to upgrade to the latest release.

Bump the version of the develop branch

You will need to checkout the develop branch of geode and geode-examples.

1. update gradle.properties
   1. 1. update the version property to the next release version and ensure that it has -SNAPSHOT on the end. (for example: if you created release branch for 1.8.0 update version number to 1.9.0-RELEASE on the develop branch)
2. if not a patch release, update geode-core/src/main/java/org/apache/geode/internal/Version.java

   1. 1. Add the new ordinal for the new version

         New ordinal

         //Add 5 to the previous ordinal
         private static final byte GEODE_1_9_0_ORDINAL = 100;

      2. Add the new version 

         Adding the new version

         public static final Version GEODE_1_9_0 =
               new Version("GEODE", "1.9.0", (byte) 1, (byte) 9, (byte) 0, (byte) 0, GEODE_1_9_0_ORDINAL);

      3. Set the current version to the new version

         Set current to new version

         public static final Version CURRENT = GEODE_1_9_0;

         
         
         

      4. Update the highest version

         Set current to new version

         public static final int HIGHEST_VERSION = 105;

3. if not a patch release, update geode-core/src/main/java/org/apache/geode/internal/cache/tier/sockets/CommandInitializer.java

   1. 1. Add the next version to addCommands

         CommandInitializer

         allCommands.put(Version.GEODE_1_9_0, geode18Commands);

         
         

4. Update the version in geode-book/config.yml and geode-book/redirects.rb on develop.  Note: do NOT include the patch digit in product_version_nodot in config.yml, even for patch releases

5. Update the expected-pom.xml files

   gradle build

   ./gradlew clean
   ./gradlew build -Dskip.tests=true #note: ok if build fails expected pom test
   ./gradlew updateExpectedPom

6. Review the benchmark baseline.  In theory this could be updated to the new release branch, but the highwater tag is preferable.

   See ci/pipelines/shared/jinja.variables.yml around line 19:

    benchmarks:
      baseline_branch: develop/highwater
      baseline_version: ''
      benchmark_branch: develop

7. Publish the develop branch to origin

   Publish the changes to develop

   git add .
   git commit -a -m "Upgraded version number for releasing 1.x.x"
   pit push origin develop

8. Plus the BumpMinor task to increment the concourse version in the apache-geode concourse pipeline at: 
   https://concourse.apachegeode-ci.info/teams/main/pipelines/apache-develop-main?group=Semver%20Management
   (if you do not have concourse permissions to plus jobs, ask on the dev list)

9. Update the version and geodeVersion in gradle.properties file of the geode-example develop branch to the next release version

   git checkout develop
   version = 1.9.0-SNAPSHOT
   geodeVersion = 1.9.0-SNAPSHOT
   git add -p
   git commit
   git push origin HEAD

10. In Jira, add new version of develop: go to https://issues.apache.org/jira/projects/GEODE?selectedItem=com.atlassian.jira.jira-projects-plugin:release-page and fill in the new version and click Add (note: you must be in the Jira Administrators group to do this, ask on the dev list if you are not).

Validate Fix Versions in JIRA

Occasionally someone will have assigned the the wrong fix version to JIRA tickets. This might result in users expecting a fix or feature to be in a release when it in fact is not. To avoid confusing or misleading our users, we need to validate that a) everything that's labeled to be in this release is in fact there and vice versa that everything that is in the release, also is marked accordingly in JIRA.

Several community members have written scripts that automate at least some of those tasks in the past.

To validate that every ticket has a corresponding commit and vice versa, you could use this script.

Validate ticket has matching commit

If a ticket doesn't have a matching commit, you might take the following investigation steps:

1. Look through ticket and commits to see if this was just a revert.
2. Does the ticket reference a PR?
3. If this is about a specific file, take a look at the file's history
4. Ping the ticket assignee

If it turns out the ticket wasn't resolved in this release, adjust the fix version.

Validate all changes have a matching ticket

If a commit mentions a JIRA ticket which isn't marked as fixed or where there is no matching JIRA ticket, you might consider the following steps:

Check if there is any matching JIRA ticket. If so, why isn't it closed?

If there is no matching JIRA ticket, take a look at the commit and the PR and see if you can find more information from there.

Validate tickets are marked as fixed

Sometimes tickets get marked with a fixVersion, but then get reopened or don't get marked as fixed. This can lead to false information if someone looks at release notes. The below JIRA query should find those tickets:

project = GEODE AND fixVersion = <current release> AND resolution != Fixed

Creating a Release Candidate

Accept critical fixes to the release branch

It is expected that some stabilization work may be needed once the release branch is cut.

Proposals to bring completed and tested fixes from develop to the release branch may be made to the dev list.  The release manager may join the conversation if needed to remind the community of the process, for example: 

Hi <thread participant(s)>, thank you for bringing your concern.

Geode's release process dictates a time-based schedule to cut release branches.  Once cut, the “critical fixes” rule allows critical fixes to be brought to the release branch by proposal on the dev list.

If there is consensus from the Geode community that your proposed change satisfies the “critical fixes” rule, I will be happy to bring it to the {version} release branch.

Regards
{Release Manager}

If three +1's are received and no minus 1's, the release manager should:

• confirm that the ticket is already in a resolved state on develop
• confirm the exact commits on develop
• cherry pick to the release branch
  • git cherry-pick -x {SHA} && ./gradlew build 
  • if fix does not cherry-pick and build cleanly, ask that a PR be submitted against the release branch
• send a notification to the thread and mark the issue with the correct fixed-in version in Jira:

There appears to be consensus that this is a critical fix.

The following commit has been brought into release/{version} as the critical fix for GEODE-XXXX:

git cherry-pick -x {SHA}

GEODE-XXXX has been marked as 'resolved in' {version}.

Regards
{Release Manager}

Please note that there is no required voting period to bring a critical fix; it can be merged immediately upon getting 3 +1's.  However, the release manager should monitor and revert it from the release branch if it causes test problems, or further discussion of the fix leads to any "minus 1".

Create the release candidate

1. From one directory above a checkout of latest geode develop, run the prepare_rc script (a release-n.n.n-workspace dir will be created in the current directory).  This script assumes there is a release/X.Y.Z branch pushed to geode, geode-native, and geode-examples.  It will checkout the tip of that branch for all repos, build them, and prepare the artifacts. It will also prepare RC tags in each repository and finally pre-stage to nexus.  Do not run this in a remote shell or headless environment, as a GUI is required to prompt for your GPG passphrase (several times) and your ASF LDAP password (Apache password). Do not include @apache.org in your apache username.

   geode/dev-tools/release/prepare_rc.sh -v 1.9.0.RC1 -k last_8_digits_of_your_gpg_key -a your_apache_ldap_username

2. The "next steps" printed out at the end of the prepare_rc script will walk you through the remaining steps to finalize nexus staging (pictured below), publish the release candidate, and send the VOTE email.

3. 

If there is an older geode staging repository listed (from a previous RC, make sure you drop it. Find "orgapachegeode-####" and click on "Drop"

Sanity Check

Before giving the RC to the community to validate, make an rc pipeline to validate that the artifacts are viable:

geode/dev-tools/release/deploy_rc_pipeline.sh -v 1.9.0

Send out an email announcing the RC

The last instruction from the prepare_rc script will be to run the commit_rc script.  When that is complete, it will print out the contents of the email for you to send (and also copy it to your clipboard, if you have pbcopy installed).  If you need to re-generate the email for any reason, use geode/dev-tools/release/print_rc_email.sh.  Send the email to the dev@geode.apache.org with subject "[VOTE] Apache Geode <ver>RC<rc>".  

Tally the votes

After the deadline has passed, reply to the VOTE thread with a voting result summary similar to the following (use the PMC roster to determine which votes are binding):

It's past the announced deadline and we have enough votes to close the vote.

Voting status
==========
+1: 3 binding votes
* Name (PMC member)
* Name (PMC member)
* Name (PMC member)
* Other Name
* Other Name

+0: zero votes

-0: zero votes

-1: zero votes

The voting meets the requirements of at least 3 PMC members with +1 votes and has the required majority of +1 votes.
Apache Geode {ver}.RC{n} passed the vote and we will finalize the release shortly.

Thanks everyone for the great work!

-{Release Manager}

If not enough votes are received, the release manager may, at their discretion, extend the voting deadline, or close the vote and start a DISCUSS thread on whether to abandon the release or try again.

If the voting is successful, proceed to the next section.  If showstopper issues were raised, create a new release candidate.  If the release is to be abandoned, destroy the pipeline, release branch, and staged artifacts in nexus and svn.

Finalizing the Release

Promote the release candidate to final release

Once a release candidate has been approved:

1. Click 'Release' in http://repository.apache.org/ (pictured below step 5)
2. Fork https://github.com/Homebrew/homebrew-core
3. Make sure you can run docker info and docker images.  If you are on Linux, you may first need to do: sudo groupadd docker && sudo usermod -aG docker $USER

4. From the same directory you ran the previous release scripts, run the promote_rc script (note: you must be a Geode PMC member to commit to dist/release/geode):

   geode/dev-tools/release/promote_rc.sh -v 1.9.0.RC1 -k 'your_40_digit_gpg_key' -g your_github_username

5. The "next steps" printed at the end of the promote_rc script will walk you through the remaining tasks to validate the docker image, update Jira, wait overnight for mirrors to sync, make the brew PR, then finalize the release.
   
   

Transition JIRA issues fixed in this release from Resolved → Closed

1. Mark the version as released in Jira: go to https://issues.apache.org/jira/projects/GEODE?selectedItem=com.atlassian.jira.jira-projects-plugin:release-page and click on the ... to get the Actions pop-up menu and click Release (note: you must be in the Jira Administrators group to do this, ask on the dev list if you are not).

2. List all the JIRAs with fix version as the release version and status as resolved.
   
   
   
   
3. Using bulk operations → transition to closed state.
   
   
   
   
   
   
   
   
   
   
   

Mark the version as released in JIRA

Go to https://issues.apache.org/jira/plugins/servlet/project-config/GEODE/administer-versions?status=unreleased . Click on the "..." under actions for the version you are releasing and select "Release version".

Wait for mirror sites to sync

*** this is a good time to call it a day...mirrors take overnight to sync the new release ***

Finalize the release

1. Confirm that your brew PR has been closed and brew install apache-geode picks up the new release.  

   brew install apache-geode
   gfsh version

2. From the same directory you were in when you ran the previous release scripts, run finalize_release.sh:

geode/dev-tools/release/finalize_release.sh -v 1.9.0

The "next steps" printed out at the end of the finalize_release script will walk you through the remaining steps update mirror links, publish docs site, and send the official release announcement.

Publish javadocs and documentation to the website

Ask on the dev list if you need help with these steps.

1. Update links to previous releases that appear on https://geode.apache.org/releases/.  The finalize_release script may have removed some old version from the mirror site, if so, the links on the "downloads" web page should be changed to point to the archive site instead, i.e.

   1. change the links for any old versions removed by finalize_release.sh that contain closer.cgi to archive, e.g.:
      1. before: http://apache.org/dyn/closer.cgi/geode...
      2. after: http://archive.apache.org/dist/geode...
   2. change the .asc/.sha256 links like this:
      1. before: https://www.apache.org/dist/geode...
      2. after: https://archive.apache.org/dist/geode...
2. Build website from sources as described in geode-site/website/README.md.
3. In the generated site, create the directory geode-site/content/releases/latest.
4. Obtain a copy of the javadoc directory from the binary release and put it in the geode-site/content/releases/latest directory (link from the website's Docs landing page points to ../releases/latest/javadoc).
5. Deploy the generated site by checking it into the asf-site branch of the apache-geode repo.
   
   

Update dependencies

Now is the best time to bump dependency versions on the various 3rd-party libraries used by Geode.  Start a DISCUSS thread asking for a volunteer to lead this effort.

Send the announce mail

To:  user@geode.apache.org, announce@apache.org, dev@geode.apache.org

Subject: [ANNOUNCE] Apache Geode 1.9.0

*** Important: Send the email from your apache email ID*** (otherwise announce@apache.org will bounce. See https://reference.apache.org/committer/email for how to send email from your apache email address)

The Apache Geode community is pleased to announce the availability of
Apache Geode {version}.

Apache Geode is a data management platform that provides a database-like
consistency model, reliable transaction processing and a shared-nothing
architecture to maintain very low latency performance with high concurrency
processing.

Geode {version} contains a number of improvements and bug fixes. It includes performance improvements in OQL order-by and distinct queries in client/server when security is enabled. New GFSH commands were added to get/set cluster config and to destroy gateway receivers. A new post processor was added to the new client protocol. Pulse now supports legacy SSL options. Auto-reconnecting members no more reuse old addresses and IDs. Duplicated or member-specific receivers are removed from cluster config during rolling upgrades. Users are encouraged to upgrade to the latest release.
For the full list of changes please review the release notes:
https://cwiki.apache.org/confluence/display/GEODE/
Release+Notes#ReleaseNotes-{version}

The release artifacts can be downloaded from the project website:
http://geode.apache.org/releases/

The release documentation is available at:
http://geode.apache.org/docs/guide/{version eg. in the format as 17 or 18 or 19}/about_geode.html

We would like to thank all the contributors that made the release possible.
Regards,
{Release Manager} on behalf of the Apache Geode team