Skip to content

How to release

Jump to bottom
Ravi Sharda edited this page Sep 30, 2020 · 5 revisions

Here are the instructions on how to release the pravega-keycloak-client library.

To perform a release, you will need the following:

  1. A set of GPG signing key and password, which will be used for signing the artifacts. Follow the instructions in https://help.github.com/en/articles/generating-a-new-gpg-key for generating and configuring one.
  2. Sonatype username/password with access to publish artifacts to the io.pravega group.

I. Preparing the branch

Preparing the branch consists of making any necessary changes to the branch you will be working on as part of releasing. There are two possible situations:

  • Bug-fix release: This is a minor release version over an existing release branch
  • Feature release or non-backward-compatible release: This is a change to either the first or the middle digit, and it requires a new release branch.

Bug-fix release

If this is a bug-fix release, then there is no need to create a new branch. First, identify the branch you'll be working on. It will be named rX.Y, e.g., r0.8. The preparation consists of:

  1. Changing buildVersion in gradle.properties from X.Y.Z-SNAPSHOT to X.Y.Z. For example, if the current value is buildVersion=0.8.0-SNAPSHOT, then change it to buildVersion=0.8.0.
  2. Raise a PR with the change and get it merged. Here's an example PR.
  3. Tag the commit with vX.Y.Z-rc0. For example, v0.8.0-rc0.

A couple of observations about step 3:

  1. There are two ways to tag:

    • Via the command line:
       > git checkout rX.Y
   > git tag vX.Y.Z-rc0
   > git push upstream vX.Y.Z-rc0

    Make sure you have your upstream remote set up correctly

    • Via GitHub releases: when creating a release candidate, GitHub automatically creates the tag for you in the case one does not exist yet. We will take more about release candidates in a minute.

  2. It is possible that a release candidate is problematic and we need to do a new release candidate. In this case, we need to repeat this tagging step as many times as needed. Note that when creating a new release candidate tag, we do not need to update the Pravega Keycloak Client version.

Major release

A major release changes either the middle or the most significant digit. In this case, you do need to create a new branch. The process is the following, assuming for the sake of example that the new release is 0.8.0:

  > git checkout master
  > git tag branch-0.8
  > git push upstream branch-0.8
  > git checkout -b r0.8
  > git push upstream r0.8

Once the steps above are done, we need to make version changes to both master and the release branch (say, r0.8 branch):

  • In master, create an issue and corresponding pull request to do the following (See example PR for 0.8.0 release):

    • Modify the pravegaVersion in gradle.properties to the latest release version (say, 0.8.0).
    • Bump up the buildVersion in the same file (say, 0.9.0-SNAPSHOT).

  • For the release branch (r0.8), create an issue and corresponding pull request to do the following (See example PR for 0.8.0 release):

    • Update the pravegaVersion in gradle.properties to the latest version (say, 0.8.0).
    • Remove snapshot from buildVersion in the same file to the target version (say, from buildVersion=0.8.0-SNAPSHOT to buildVersion=0.8.0)

Once the last change is merged, we need to tag the commit point in the same way we described for a bug-fix release. See the instructions in the previous section.

II. Pushing a release candidate (RC) out

If needed, release RC builds. Once the RC builds are validated, you could promote them to a final release (as described in section III below).

Step 1: Create a pre-release on GitHub

On the GitHub repository page, go to releases and create a new draft. On the draft:

  • Mark it as a "pre-release".
  • Fill out the tag field. Note that this is a release candidate, so the tag should look like vX.Y.Z-rcA (ex: v0.8.0-rc0)

Step 2: Build and push the distribution to Maven

First, update the property signing.keyId in gradle.properties with your signing key (looks like 00B5050F).

Then execute the following command (after replacing the <params>):

./gradlew clean assemble publish -PpublishRepo=mavenCentral \ 
-PdoSigning=true -Psigning.password=<your-signing-key-password> \ 
-PpublishUsername=<sonatype-oss-username> -PpublishPassword=<sonatype-oss-password>

Step 3: Verify the published builds

  • Login to Nexus Repository Manager using sonatype credentials with write access to io.pravega group.
  • Under Build Promotion -> Staging Repositories, locate the staging repository that was created for the latest publish (format iopravega-XXXX, for example iopravega-1004)
  • Select the repository and select the Close button in the top menu bar. This will perform validations to ensure that the contents meets the maven requirements (contains signatures, javadocs, sources, etc). This operation takes a short time to complete, press the Refresh button in the top menu bar occasionally until the operation completes.
  • Once the operation completes, locate the URL field in the Summary tab of the newly closed repository (it will be something like https://oss.sonatype.org/content/repositories/iopravega-XXXX where XXXX is the number of the staging repository). This should be tested to ensure that all artifacts are present and functions as expected.

Step 4: Create a file containing all the commits.

git log <commit-id-of-last-release>..<latest-commit-id-of-release-branch> > commits.txt
git log e49f9a6050ab5c76f44004a3289d047fe674cb55..dd3fea799d9b5f6ceb85304d73ed4410dfbbc632 > commits.txt

Step 5: Update release notes in the pre-release.

Attach the commits.txt file generated in the last step and draft release notes.

Step 6: Publish the Github release.

Publish the release candidate by clicking on the button on the draft page. Once published, request the developers and community to validate the candidate.

III. Releasing

The steps are the same as the steps required for publishing the RC builds. There is one minor difference in "step 3: Verify the published builds".

Change the Pravega version.

Once the release is done, create an issue and corresponding pull request to change the buildVersion=0.8.0 in gradle.properties to X.Y.(Z+1)-SNAPSHOT (for example 0.8.1-SNAPSHOT) for the release branch.

Clone this wiki locally