...

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 Make sure you have the latest patch release of OpenJDK 1.8.0 (and not Oracle JDK).
6. Homebrew (optional) → https://brew.sh/
7. fly → use platform-appropriate download link in bottom right corner of https://concourse.apachegeode-ci.info (ensure you have access to the Geode CI, login via the webpage, if access is needed send a request to the Dev list dev@geode.apache.org)
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

...

...

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 Confirm that the Geode LICENSE and NOTICE files accurately reflect what is on develop . (ask for help on the dev list if you are not sure how to confirm this).

Branching for release

Create the release branches

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 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)

   Code Block
   language bash
   git checkout develop git checkout -b release/{version} [GOOD_SHA]

   
   

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

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

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

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

    

8. Update JAR name used in org/apache/geode/session/tests/Tomcat8ClientServerRollingUpgradeTest.java

   1.   Remove `-SNAPSHOT` from the following lines:

      Code Block
      language yml
      "/lib/geode-modules-" + currentVersion + "-SNAPSHOT.jar", "/lib/geode-modules-tomcat8-" + currentVersion + "-SNAPSHOT.jar",

      
      

   2. the resulting change will look like:

      Code Block
      language yml
      "/lib/geode-modules-" + currentVersion + ".jar", "/lib/geode-modules-tomcat8-" + currentVersion + ".jar",

      
      

9. Review the benchmark baseline.  It should be the more recent of {previous release} or develop/highwater.  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:

   Code Block
   language yml
   benchmarks: baseline_branch: develop/highwater baseline_version: '' benchmark_branch: release/{version}

   
   

10. Publish the release branch to origin

    Code Block
    language bash
    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.

    Code Block
    language bash
    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

    No Format
    version = 1.7.0 geodeVersion = 1.7.0

    
    

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

    
    

    Code Block
    language bash
    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

    
    

    Code Block
    language bash
    git checkout develop git pull git checkout -b release/{version} git push origin HEAD

    
    

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

    
    

    Code Block
    language bash
    git checkout develop git pull git checkout -b release/{version} git push origin HEAD

    
    

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

    No Format

    Hello Geode Dev Community, We have created a new release branch for Apache Geode {version} - "release/{version}" PleaseWe dohope reviewto andmake raisea anyfinal concern withrelease in about a month. Please focus your acceptance testing on this branch and raise any concerns in the releasenext few branchweeks. If noAfter concernssome arequiet raised,period we will startmove withto theformally votingpackage for thea release candidate soon and vote upon it. Regards {Release Manager}

    
    

17. Create the concourse release pipeline.

    Code Block
    language bash
    fly -t concourse.apachegeode-ci.info-main login --concourse-url https://concourse.apachegeode-ci.info/ cd ci/pipelines/meta ./deploy_meta.sh

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

Begin preparing release documentation

...

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

...

1. This script takes 1-2 hours.  There is no need to manually unpause any jobs. If the script fails at any point, or any -meta or -images pipeline job fails, fix the problem (if applicable) and rerun ./deploy_meta.sh to try again.  Repeat until deploy_meta exits with "Successfully deployed...-main"

    
2. For the duration of the release process, continue to monitor the new release pipeline and address any issues that may arise, including analyzing any test failures.

Bump the version of the develop branch

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

1. 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)

2. 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 see the Add button; request permission on the dev list if you don't see it).

3. 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)
4. update geode/ci/pipelines/shared/jinja.variables.yml

   1. 1. update the metadata initial_version property to the next release version

         Code Block
         language java title New ordinal
         metadata: initial_version: 1.13.0

         
         

5. if not a patch release, update geode-serialization/src/main/java/org/apache/geode/internal/serialization/Version.java

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

         Code Block
         language java title New ordinal
         //Add 5 to the previous ordinal private static final byte GEODE_1_13_0_ORDINAL = 120;

         
         

      2. Add the new version 

         Code Block
         language java title Adding the new version
         public static final Version GEODE_1_13_0 = new Version("GEODE", "1.13.0", (byte) 1, (byte) 13, (byte) 0, (byte) 0, GEODE_1_13_0_ORDINAL);

         
         

      3. Set the current version to the new version

         Code Block
         language java title Set current to new version
         public static final Version CURRENT = GEODE_1_13_0;

         
         
         

      4. Update the highest version

         Code Block
         language java title Set current to new version
         public static final int HIGHEST_VERSION = 120;

         
         

6. 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

         Code Block
         language java title CommandInitializer
         allCommands.put(Version.GEODE_1_13_0, geode18Commands);

         
         

         
         

7. 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

8. Update the expected-pom.xml files

   Code Block
   language bash title gradle build
   ./gradlew clean ./gradlew build -Dskip.tests=true #note: ok if build fails expected pom test ./gradlew updateExpectedPom

   
   

9. Review the benchmark baseline.  In theory this could be updated to the new release branch, but the highwater tag is preferable Ask on the dev list if you are unsure whether the last release branch or a highwater tag makes the most sense.

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

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

   
   

10. Publish the develop branch to origin

    Code Block
    title Publish the changes to develop
    git add . git commit -a -m "Upgraded version number for releasing 1.x.x" pit push origin develop

11. 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)

12. 
    

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

    Code Block
    language bash
    git checkout develop version = 1.9.

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

    Code Block
    language bash
    git checkout develop version = 1.9.0-SNAPSHOT geodeVersion = 1.9.0-SNAPSHOT git add -p git commit git push origin HEAD

14. 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:

...

Validate Fix Versions in JIRA

There are two parts to this audit:

1. Does every commit since the last release branch have a corresponding Jira ticket marked as Fixed in this version?
2. Can every Jira ticket marked as fixed in this version be traced to a commit in this release branch?

To help automate the process of identifying commits and tickets in need of review, you may find this script useful, or create your own script.

Tips:

• If a Jira ticket is fixed on develop AND cherry-picked to a release branch, it should list both fix versions.
• If a Jira ticket is fixed by way of another commit or Jira ticket, there should be a comment detailing this.
• If a Jira ticket is partially fixed but there is more work to be done in the next release, splitting into two tickets may be the best way to represent that.
• Don't forget about geode-native.  It's a separate git repository but uses GEODE Jira tickets and is released as part of Geode.
• Be mindful of revert commits
• Be mindful of Jira tickets resolved as "Won't Fix", "Duplicate" etc.
• Be mindful of Jira tickets that were re-opened, but the Fixed version was never cleared.
• For changes that came in close to the time a release branch was cut, double-check whether the fix actually made it onto the branch.  The list of release start dates can be helpful, but checkout the release tag to confirm for certain. 
• When in doubt, reach out to people that have been involved the with ticket to confirm its status.  Many times they just forgot to marked it fixed when their PR got merged, or forgot to fill in the fixed version.

Begin preparing release documentation

1. Start preparing the release docs at Release Notes. Ask the community for suggestions on fixes and features to highlight, or go through the commits yourself and choose 5-10 items of interest. 

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:

   
   

   No Format

   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.

   
   

Creating a Release Candidate

...