This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Page tree
Skip to end of metadata
Go to start of metadata

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

Software dependencies

  1. git →  https://git-scm.com/downloads
  2. docker → https://docs.docker.com/docker-for-mac/install/ 
  3. svn → shipped with MacOS [install with command line tools → https://stackoverflow.com/questions/9329243/xcode-install-command-line-tools]
  4. gpg tools → https://gpgtools.org
  5. web browser → https://support.google.com/chrome/answer/95346?co=GENIE.Platform%3DDesktop&hl=en
  6. java JDK → https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html
  7. text editor : vi → should be pre-installed
  8. Homebrew → https://brew.sh/
  9. fly → use platform-appropriate download link in bottom right corner of https://concourse.apachegeode-ci.info
  10. cmake, doxygen, and openssl - install with brew on mac (brew install doxygen && brew install cmake && brew install openssl)

Permission and keys:


Permission and Keys:

  • Ensure that the release manager has bulk modification permissions on Apache Geode JIRA.

To verify

    1. Go to : https://issues.apache.org/jira/secure/Dashboard.jspa→ login → Issues → Search for Issues → select Geode in the Project list
    2. After logging in, on the top right side of the page click on Tools → Bulk Change → Current Page
    3. Select any ticket and click Next
    4. The Transition Issue option should not be blocked as N/A. If it is not blocked means that you have bulk operation permission.
    5. If you don't have permissions, send a mail requesting permission to dev@geode.apache.org.
  • Ensure you have permission to modify the wiki for the release docs : Release Notes
  • The release manager will need to have a Docker Hub credential that has permission to upload Apache Geode to Docker Hub. To get permissions follow the steps below
    1. If you don't have a docker hub account create one at https://hub.docker.com/
    2. After creating the docker hub ID, send an email to dev@geode.apache.org requesting access to upload Apache Geode artifacts to Docker Hub mentioning your docker id.


  • Ensure that you have a valid pgp key.
    1. For MacOS use https://gpgtools.org/
    2. For Ubuntu https://askubuntu.com/questions/100281/how-do-i-make-a-pgp-key
    3. Ensure that the public key is published and uploaded to servers.
    4. Ask a fellow committer to co-sign the keys, this ensures that the keys are available on public servers.
    5. If you are using GPG Tools >= 2.1, export your secret key to a file to be used by Gradle. You can export it with `gpg --export-secret-keys >~/.gnupg/secring.gpg`
  • Add your public key block to KEYS file in develop branch if they are not already present in it.
    1. On MacOS : (More information available at https://www.apache.org/dev/release-signing.html#basic-facts)

      On MacOS terminal
      (gpg --list-sigs <your name> && gpg --armor --export <your name>) >> keys.log
    2. Take the contents of keys.log and append it to KEYS file in the develop branch of Apache Geode. Commit and push to origin.
    3. Also, add the key fingerprint to https://id.apache.org under OpenPGP Public Key Primary Fingerprint. The fingerprint can be found in the GPG Keychain in MacOS or the second line of the command executed in step a.
    4. Also upload your public key into keyserver
      1. http://pool.sks-keyservers.net:11371
      2. http://keyserver.ubuntu.com:11371
    5. Sample key block which needs to be appended to the KEYS file in develop:

      pub   rsa4096 2018-01-04 [SC] [expires: 2022-01-04]
            CE6CD0A89480B1B9FCB98699274C66710770C135
      uid           [ultimate] Nabarun Nag <nag@cs.wisc.edu>
      sig 3        274C66710770C135 2018-01-04  Nabarun Nag <nag@cs.wisc.edu>
      sig 3        C8D3705F9DBE2177 2018-02-26  Jason Huynh <jasonhuynh@apache.org>
      sub   rsa4096 2018-01-04 [E] [expires: 2022-01-04]
      sig          274C66710770C135 2018-01-04  Nabarun Nag <nag@cs.wisc.edu>
      
      -----BEGIN PGP PUBLIC KEY BLOCK-----
      
      mQINBFpOogwBEADlT2Ue6XDFHqbM/LbZXhHMw4rcT4ifuBGyibbUbhLWGimav5tI
      buGRxOViV2q5FNIEYK6Gyfr1kKTlBxCZxkmbNj5lyqgBM7HfL0sTQ2kGd9IE7rPz
      KQ65yzUdKd4Aacm9Zlfja6pV6vYbMBdd4gcGFfsobh4yD0dZFXBlkEiqKV89PhxG
      h9PaBFN6FfDYTaUwir2MveV54N5ynPKcVt9Ler5v6wo/1Mr+bxoZ5dy15UMqxgHT
      YfRDGmLvCPjI0Aabc86bzgi8FJ8QdW1/oBLH/fjDardQOSgGCI7Smz4F52LGXb7Z
      .
      .
      .
      Y79TWNoe0dBLf6B8dmX+aqfWhziCz2Ijy8lF8sfQl2DalG+YpBkBBsNs8j/6lpHr
      Fgh2AddGmNuaP+tMFGCtdeHujkSbx7b1UOkxgLTS7nsRM0l6QN4czTNYcaUFgVU4
      Ig==
      =VFqr
      -----END PGP PUBLIC KEY BLOCK-----
      
      
      

Discussion on JIRAs

Send a [DISCUSS] email to dev@geode.apache.org informing developers that a new release branch is about to be created.

Request developers to respond back if they are waiting to finish a JIRA issue, or feel that a particular JIRA / fix must be included in the release.

Once the discussion comes to a conclusion and everything that is necessary for the release is present in the develop branch we start with creating the release branch.

Creating 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/beta/teams/main/pipelines/develop/jobs/UpdatePassingRef.
  2. 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 resolve/close it or if not fixed then increment the fix version in the ticket
  3. Create the release branch.

    Create release branch
    git checkout -b release/{version}
  4. gradle.properties

      1. remove -SNAPSHOT in releaseType 
  5. Update the version number in all the expected pom files. Doing it manually takes a lot of time. If you choose to do it I have listed the files below. Otherwise please use the script below to do it.

    Updating the expected-pom files

    - build geode after the version is updated in gradle.properties. NOTE: The build will fail but will have the correct expected-pom.xml files

    gradle build
    ./gradlew clean build -Dskip.tests=true

    - Update dependency versions using gradle task updateExpectedPom.

    gradle uEP
    ./gradlew uEP

    - Publish the release branch to origin

    Publish the release branch
    git add .
    git commit -a -m "Upgraded version number for releasing {version}"
    pit push origin release/{version}
  6. Now checkout the repo for geode-examples and create a release branch.

    Create release branch
    git checkout develop
    git checkout -b release/{version}
  7. Update the version number in gradle.properties of geode-examples

    version = 1.7.0
    geodeVersion = 1.7.0
  8. Commit the version changes and push the release branch of geode-examples
    git add -p
    git commit
    git push origin HEAD
  9. Checkout the repo for geode-native and create a release branch
    git checkout develop
    git checkout -b release/{version}
    git push origin HEAD
  10. 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}


  11. Setting up concourse release pipeline

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

Release Doc preparation:

  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.

Prepare develop branch for the next release

  1. gradle.properties
      1. update versionNumber to the next release version (for example: if you created release branch for 1.8.0 update version number to 1.9.0 in the below files in develop branch)
      2. ensure that releaseType has -SNAPSHOT in it.
  2. geode-core/src/main/java/org/apache/geode/internal/Version.java
      1. Add the new ordinal

        New ordinal
        //Add 5 to the previous ordinal
        private static final byte GEODE_190_ORDINAL = 100;
      2. Add the new version 

        Adding the new version
        public static final Version GEODE_190 =
            new Version("GEODE", "1.9.0", (byte) 1, (byte) 9, (byte) 0, (byte) 0, GEODE_190_ORDINAL);
      3. Set the current version to the new version

        Set current to new version
        public static final Version CURRENT = GEODE_190;



      4. Update the highest version

        Set current to new version
        public static final int HIGHEST_VERSION = 105;
  3.  geode-core/src/main/java/org/apache/geode/internal/cache/tier/sockets/CommandInitializer.java
      1. Add the next version to addCommands

        CommandInitializer
        ALL_COMMANDS.put(Version.GEODE_190, commands);


  4. Update the version in geode-book/config.yml and geode-book/redirects.rb on develop.
  5. Update the expected-pom.xml files

    Updating the expected-pom files

    - build geode after the version is updated in gradle.properties. NOTE:The build will fail but will have the correct pom-default.xml files

    gradle build
    ./gradlew clean build -Dskip.tests=true

    - Update dependency versions using gradle task updateExpectedPom.

    gradle uEP
    ./gradlew uEP

    - Publish the develop branch to origin

    Publish the release branch
    git add .
    git commit -a -m "Upgraded version number for releasing 1.x.x"
    pit push origin develop
  6. Update the benchmark baseline to the release branch you just created.

    E.g. in ci/pipelines/shared/jinja.variables.yml around line 59:

    set baseline_branch: "release/1.10.0"
    set baseline_version: ""
  7. Update the version in geode-example develop branch.

    Update the version in gradle.properties to the next release's snapshot

    git checkout develop
    version = 1.9.0-SNAPSHOT
    geodeVersion = 1.9.0-SNAPSHOT
    git add -p
    git commit
    git push origin HEAD
  8. 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.

Creating the release candidate:

  1. From a checkout of geode, run the prepare_rc.sh script. Run this command on a machine using GUI as you will be prompted to enter PGP key password. You will see messages like "Could not find metadata org.apache.geode:geode-cq/maven-metadata.xml" on your terminal. Ignore them.

    cd dev-tools/release
    ./prepare_rc.sh -v version_with_rc -k your_8_digit_key_id

    This script assumes there is a release/X.Y.Z branch pushed to all of the geode repositories (geode, geode-native, geode-examples). It will checkout the tip of that branch for all repos, build them, and copy the artifacts to the build/dist directory. It will also tag the RC in each checkout.

    If you are running on linux, you may see this error message:

    error: gpg failed to sign the data

    error: unable to sign the tag

     If you get that error message, try to sign some random file so that gpg will unlock your keyring. After that the git tag -s should work.

  2. Review the artifacts and revisions under build before moving in to publishing. You should see these directories
    1. geode - This is your geode checkout. It should have a tag for your release, eg rel/v.1.9.0.RC4. Make sure that the revision that was built is correct
    2. geode-examples - The geode examples checkout. Again, check the revision
    3. geode-native - The geode native checkout.
    4. dist   - This is an svn checkout of apache's staging area. It will have artifacts added, but not committed. Review the added artifacts. You should see something like this:

      dist> svn status
      A       dev/geode/1.9.0.RC5
      A       dev/geode/1.9.0.RC5/apache-geode-1.9.0-src.tgz
      A       dev/geode/1.9.0.RC5/apache-geode-1.9.0-src.tgz.asc
      A       dev/geode/1.9.0.RC5/apache-geode-1.9.0-src.tgz.sha256
      A       dev/geode/1.9.0.RC5/apache-geode-1.9.0.tgz
      A       dev/geode/1.9.0.RC5/apache-geode-1.9.0.tgz.asc
      A       dev/geode/1.9.0.RC5/apache-geode-1.9.0.tgz.sha256
      A       dev/geode/1.9.0.RC5/apache-geode-examples-1.9.0.tar.gz
      A       dev/geode/1.9.0.RC5/apache-geode-examples-1.9.0.tar.gz.asc
      A       dev/geode/1.9.0.RC5/apache-geode-examples-1.9.0.tar.gz.sha256
      A       dev/geode/1.9.0.RC5/apache-geode-examples-1.9.0.zip
      A       dev/geode/1.9.0.RC5/apache-geode-examples-1.9.0.zip.asc
      A       dev/geode/1.9.0.RC5/apache-geode-examples-1.9.0.zip.sha256
      A       dev/geode/1.9.0.RC5/apache-geode-native-1.9.0-src.tar.gz
      A       dev/geode/1.9.0.RC5/apache-geode-native-1.9.0-src.tar.gz.asc
      A       dev/geode/1.9.0.RC5/apache-geode-native-1.9.0-src.tar.gz.sha512
      
      
  3. If everything looks good, publish the artifacts to the nexus staging repositories. You will be prompted to enter your ASF LDAP password (Apache password)

    cd build/geode
    ./gradlew  publish -Paskpass -Psigning.keyId=last_8_characters_of_your_gpg_fingerprint -Psigning.secretKeyRingFile=${HOME}.gnupg/secring.gpg -PmavenUsername=your_apache_ldap_username
  4. Verify that all the artifacts have been uploaded to the nexus repository by logging into repository.apache.org and then click on close. Example:
  5. If there is an older geode staging repository listed (from a previous RC, make sure you drop it. Find "orgapachegeode-####" and clink on "Drop"
  6. Publish release artifacts to ASF dist repo. The prepare_rc.sh script should have already added artifacts in dist/dev/geode/full_version_with_rc.

    cd dist/dev/geode
    svn commit -m "Releasing Apache Geode {version}.RC# distribution"
  7. Push the release tags. These were already created (but not pushed) by the prepare_rc.sh script. Be careful as `rel/` folder is protected, once we push the release tag to server, it cannot be modified. Any other change will have to be moved to the next RC number.

    cd build/geode
    git push rel/v[version_with_rc]
    cd ../../build/geode-examples
    git push rel/v[version_with_rc]
    cd ../../build/geode-native
    git push rel/v[version_with_rc]

Send out an email announcing the RC

From within a geode checkout, run the dist/dev/print_rc_email.sh script to generate an email to send to the dev@geode.apache.org. The subject should be "[VOTE] Apache Geode 1.9.0 RC4"

./print_rc_email.sh -v 1.9.0.RC4 -m 1054


Finalizing the release

Once the release candidate has been approved 

  1. cd to the release branch for apache geode and tag the commit with the final version 

    git tag -s rel/v{version} -m "Apache Geode v1.0.0 release" rel/v{version}.RC{latest_rc}
    git push origin rel/v{version}
  2. cd to the release branch for geode-examples and tag the commit with the final version, using same commands as above

  3.  cd to the release branch for geode-native and tag the commit with the final version, using same commands as above

  4. Use svn to move the distributions from dev to release. Use the folders created in step 1 of "Creating the release candidate" section.

    # in the directory created in step 1 of "Creating the release candidate" section.
    
    cd dist
    svn mv dev/geode/{version}.RC#/ release/geode/{version}
    svn commit -m "Releasing Apache Geode {version} distribution"
  5. Update the keys in dist/release.

    # in the directory created in step 1 of "Creating the release candidate" section.
    
    
    cp dev/geode/KEYS release/geode/KEYS
    svn commit -m "Updating Apache Geode KEYS file"
  6. Promote the Nexus staging repo → login to repository.apache.org→ Select Staging repositories → Find "orgapachegeode-####" → Click on the Release Button on the toolbar.

Apache Geode JIRA 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.

  2. List all the JIRAs with fix version as the release version and status as resolved.



Using bulk operations → transition to closed state.











*** this is a good time to go home / take a nap / finish it tomorrow.  mirror sites can take 8-24 hours to sync, and the below docker and brew and announce steps depend on most or all mirrors being up-to-date.***

Upload the docker image to docker hub.

  1. docker/Dockerfile
      1. Update GEODE_GPG with your GPG fingerprint.
      2. Update GEODE_VERSION with the release version (eg. 1.8.0)
      3. Update GEODE_SHA256 with the SHA from https://dist.apache.org/repos/dist/release/geode/{VERSION}/apache-geode-{VERSION}.tgz.sha256 (Replace VERSION with the version you are trying to release).
  2. Check these changes in to the release branch. If for some reason you have already merged the release branch to master and deleted it, check the changes in to master.
  3. Follow the instruction present in docker/README.md
  4. Note that you may see a 404 error during the docker build process, because it tries a mirror first before falling back to the primary download site, and some mirror sites take 8-24 hours to sync.  As long as the docker build completes successfully you're ok.

Update the brew formula

Homebrew update (MacOS)
# update brew
brew update


# Navigate to homebrew core directory
cd /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula



# Create a release branch
git checkout -b apache-geode-{version}


#Open apache-geode.rb
vim apache-geode.rb


# add the correct version in lines below 
# in url update "https://www.apache.org/dyn/closer.cgi?path=geode/{version}/apache-geode-{version}.tgz"
# in sha256 update with the SHA256 from https://dist.apache.org/repos/dist/release/geode/{version}/apache-geode-{version}.tgz.sha256


# save the file 


#commit the file - put the right version in below command.
git add .
git commit -a -m "apache-geode {version}"


# Fork git@github.com:Homebrew/homebrew-core.git to your repositories.
#add the remote 
git remote add myfork {your forked homebrew core repo}


#push to your remote forked repo
git push myfork apache-geode-{version}


#create a PR against git@github.com:Homebrew/homebrew-core.git - monitor the the tests in the PR page


#test it locally.
git checkout master


git merge apache-geode-{version}
brew install --build-from-source apache-geode


#check for gfsh version - should be the released version
gfsh version


# uninstall apache-geode
brew uninstall apache-geode


#reset master to origin
git reset --hard origin/master



The brew team usually accepts the PR within 24 hours.  Note: they may close it without merging.  Either way, check that latest version has been added to brew by doing brew install apache-geode.

Publish javadocs and documentation to the website

  1. Build website from sources as described in geode-site/website/README.md.
  2. In the generated site, create the directory geode-site/content/releases/latest.
  3. Obtain a copy of the javadoc directory from the binary build and put it in the geode-site/content/releases/latest directory (link from the website's Docs landing page points to ../releases/latest/javadoc).
  4. Deploy the generated site by checking it into the asf-site branch of the apache-geode repo.

Destroy concourse release pipelines


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

Merge to master and destroy release branch

  1. Merge release branch to master for apache geode and then delete the release branch

    git fetch --all
    git checkout release/1.9.0
    git merge -s ours origin/master -m "Merging release/1.9.0 into master"
    git checkout master
    git merge release/1.9.0
    git push origin master
      
    git branch -D release/{version}
    git push origin --delete release/{version}
  2. Merge release branch to master for geode-examples and then delete the release branch, using same commands as above

  3. Merge release branch to master for geode-native and then delete the release branch, using same commands as above

Add released version as "old" on develop

Check out develop and add the released version and update the benchmark baseline.

Eg. in settings.gradle somewhere around line 75:

'1.9.0'].each

and in ci/pipelines/shared/jinja.variables.yml around line 59:

set baseline_branch: ""
set baseline_version: "1.9.0"

It's a good idea to make a PR for this rather than committing directly, since these changes affect tests!

Sending 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

Remove previous release from mirrors.

  1. remove from apache mirrors

    cd dist/release/geode
    svn rm {$old_release}
    svn commit -m "remove old releases (they can still be found at http://archive.apache.org/dist/geode)"
  2. update https://geode.apache.org/releases/
    1. change the links (for old versions only, not the one you just released!) that contain closer.cgi to archive, like this:
      1. before: http://apache.org/dyn/closer.cgi/geode...
      2. after: http://archive.apache.org/dist/geode...
    2. change the links for the gpg/md5 links like this:
      1. before: https://www.apache.org/dist/geode...
      2. after: https://archive.apache.org/dist/geode...