Skip to content

Release Guide

Jump to bottom
Arvind Krishnakumar edited this page Jun 26, 2020 · 21 revisions

This page describes the steps required to publish a new final release of the Okta Java SDK.

This project is released to Maven Central according to the Sonatype OSS Maven Repository Usage Guide.

Prerequisites

  • JDK 8 is installed, $JAVA_HOME is set, and $JAVA_HOME/bin is added to your $PATH

  • Git 2.0+ is installed (e.g. brew install git)

  • Maven 3.3.9+ is installed and mvn is available in your $PATH.

  • SSH Public Key - If you do not have a SSH public key yet, generate one by following the steps at https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key.

  • Go to https://github.com/settings/keys and upload your SSH public key.

  • The gpg2 encryption client is installed and in your path (e.g. brew install gpg2).

  • You have both created and distributed your GPG keys (note that if you used brew install gpg2 as recommended, the executable for these commands is gpg2 and not gpg).

  • You have created a Sonatype OSS issues account

  • You have created an issue requesting deploy permissions for the Okta Java SDK and that account has been granted release permissions to the Sonatype OSS repository for Okta.

    • The Project for the Jira issue you create on Sonatype is Community Support - Open Source Project Repository Hosting (OSSRH).

    • The Issue Type should be set to New Project.

    • For the Summary field, enter: requesting deploy rights for com.okta groupId.

    • The Group Id field should be set to com.okta.

    • The Project URL and SCM url fields should both be set to https://github.com/okta/okta-sdk-java.

    • The username field should be username you created for your sonatype account.

    • To speed things up, you could also send an email to Joel Orlina requesting him to authorize the petition in the issue. Make sure you include the link to the Sonatype Jira issue you created.

    • Note: It can take a few days for your request to be approved.

    • If you do not yet have permissions and you believe you should, open a GitHub Issue and request it and we'll work with Sonatype to grant you those permissions if you should have them.

  • You have configured $HOME/.m2/settings.xml and added the following profiles:

<servers>
...
    <server>
      <id>sonatype-nexus-snapshots</id>
      <username>your sonatype username</username>
      <password>your sonatype pass</password>
    </server>
    <server>
      <id>sonatype-nexus-staging</id>
      <username>your sonatype username</username>
      <password>your sonatype pass</password>
    </server>
...
</servers>
...
<profiles>
	...
	<profile>
	    <id>okta-signature</id>
	    <properties>
	        <gpg.executable>gpg2</gpg.executable>
	        <gpg.keyname>YOUR_GPG_KEY_NAME</gpg.keyname>
	        <gpg.passphrase>YOUR_GPG_PASSPHRASE</gpg.passphrase>
	    </properties>
	</profile>
	<profile>
	    <id>sonatype-oss-release</id>
	    <properties>
	        <gpg.executable>gpg2</gpg.executable>
	        <gpg.keyname>YOUR_GPG_KEY_NAME</gpg.keyname>
	        <gpg.passphrase>YOUR_GPG_PASSPHRASE</gpg.passphrase>
	    </properties>
	</profile>
	...
</profiles>

NOTE: At the time of this writing you will also be prompted by gpg agent.

where YOUR_GPG_KEY_NAME is the key name you gave the key when you created it and YOUR_GPG_PASSPHRASE is the passphrase you used when you created the key.

NOTE: adding these lines is a security risk if your `$HOME/.m2/settings.xml` file is readable by anyone other than you! Ensure you've protected that file, e.g.

chmod go-rwx $HOME/.m2/settings.xml
Again, the `gpg.executable` name of `gpg2` assumes you used `brew install gpg2`.
  • You have enabled both of these profiles under the <activeProfiles> element:
<activeProfiles>
    <activeProfile>sonatype-oss-release</activeProfile>
    <activeProfile>okta-signature</activeProfile>
    <!-- any others: -->
</activeProfiles>

Pre Release

Note: Occasionally, a minor version release needs to be done after new PRs have been merged to the release branch (e.g. 1.1.x). Follow the instructions here to get setup for that.

  1. Ensure the Project Documentation has been updated to document all new features and/or fixes. You will need to cut and push a new release of the documentation after you publish the Java SDK release.

  2. Ensure all changes that are to be released (including changelog edits) have been committed to the Java SDK's release branch and that the Travis CI project status representing those changes reports no errors whatsoever.

  3. Execute git status to see if there are any unnecessary files present. If you see any release process related files (ending with .release), execute mvn release:rollback and clean up.

  4. Do a dry run to verify if the release environment is setup correctly.

mvn release:prepare -DdryRun=true

Note that this step would not produce any .release files.

To cleanup after the dry-run, use:

mvn release:clean

Perform the Release

  1. After the above prerequisites have been satisfied and you have performed the pre-release verification, run the following on the command line:

    git checkout <release-branch>
# ensure git status reports no changes:
git status
# assuming no reported changes:
./src/ci/release.sh

    This will build the final versioned artifacts and upload them to the Sonatype OSS repository server in a staging repository. This is called a staged release - it is not yet available to the world.

    A staged release is fully 'done' as far as the build process is concerned, but the staged artifacts will not be released to the world in Maven Central until we log in to the repository user interface and manually execute this behavior.

    This is a really nice safety net: if there is any error at all the final versioned artifacts do not 'leak' into Maven Central, where they could be used by end-users. Only after you've ensured the release was 'clean' and that the artifacts were built as expected, and all is well, then we release the artifacts to the world.

  2. Release of the artifacts to the world - the artifacts will be propagated to Maven central repository. The sync time usually takes about 2 to 3 hours to make the artifacts available to the world.

Post Release

Project Documentation update is now fully automated.

1. GitHub Tasks

  • If necessary, create a branch for the next version (e.g. 1.1.x) from the release tag.

2. Sanity Checks

3. Email Okta DevEx Engineering Team

Notify them about the release. The email should contain the following information:

  1. A link to the previously-verified project documentation, e.g. https://developer.okta.com/okta-sdk-java/.
  2. A link to the GitHub milestone containing all issues that were resolved for the release, e.g. https://github.com/okta/okta-sdk-java/issues?utf8=%E2%9C%93&q=milestone%3A1.1.0%20is%3Aclosed%20is%3Aissue

Sample email template:

Subject: Okta Java SDK x.x.x Released!

Body:

Hi everyone,

I am pleased to announce that version x.x.x of the Okta Java SDK has just been released!

Project documentation: https://developer.okta.com/okta-sdk-java/
Change log: <<link>>

Please allow 3 to 4 hours for the release artifacts to appear in Maven Central repository before announcing the release to the Okta user community.

Cheers,
Your Name

Minor Version Release After Master Merge

You may find that days or even weeks after a release has been done, that a hotfix for a bug needs to be released. However, in the interim, other PRs may have been merged to master. Follow these steps to prepare for this kind of release.

  1. create a branch off the last release commit

    git branch <branchname> <sha1-of-commit>

  2. make your changes and commit them to the newly created branch. You can create a PR, but you will be releasing from the branch before merging to master

  3. prepare and perform the release as outlined above, but run the commands from the branch you created. At the end of this process, you will have two additional commits on your branch: 1 for preparing the release and 1 for preparing the next release.

  4. Once the release is complete, you can merge master into your branch and then merge into master.

Backing out a release if something goes wrong

The automated way

  1. mvn release:rollback
  2. Check that the pom files in Github have been rolled back
  3. git push --delete origin <TAG_NAME> (usually something like okta-sdk-root-XX, where XX is the release version)
  4. git tag -d <TAG_NAME> (same as above): removes local tag
  5. Start over: your local branch has diverged from origin, so you need to start from scratch now checking out a new fresh copy of the SDK.

Troubleshooting

During release:perform

Error

An API incompatibility was encountered while executing org.apache.maven.plugins:maven-deploy-plugin:2.8.2:deploy: org.eclipse.aether.spi.connector.ArtifactUpload.setListener(Lorg/eclipse/aether/transfer/TransferListener;)Lorg/eclipse/aether/spi/connector/ArtifactUpload

Solution

Be sure you are using Maven version 3.3.9+

Clone this wiki locally