Skip to content
This repository was archived by the owner on Dec 12, 2018. It is now read-only.

Release Guide

Jump to bottom
Micah Silverman edited this page Nov 2, 2015 · 49 revisions

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

All of Stormpath's JVM-based open-source projects are released to Maven Central according to the Sonatype OSS Maven Repository Usage Guide.

Prerequisites

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

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

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

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

  • A new Sonatype project has been created for this project - this has already been completed at this time. The guide to setup a new project for synchronization to Sonatype can be found here

  • You have created a Sonatype OSS issues account

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

    • 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.stormpath groupId

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

    • The Project URL and SCM url fields should both be set to https://github.com/stormpath/stormpath-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 Les 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>stormpath-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>

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>stormpath-signature</activeProfile>
    <!-- any others: -->
</activeProfiles>

Pre Release

  1. Ensure all changes for the version being released have been represented in the project's top-level changelog.md file in a section named after the version (e.g. 1.0.RC5.1), listing the changes associated with the release. No release should be published without appropriate change log entries!

    The new section should be written in a feature branch and then those changes should be merged into the master branch and the dev branch right before you perform the release.

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

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

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 master
# ensure git status reports no changes:
git status
# assuming no reported changes:
mvn clean
mvn release:clean
# assuming no build errors:
mvn release:prepare

    Enter the release version and the SCM release tag / label. Often retaining the defaults and hitting enter is a viable option IF you know for sure you do not need to change them:

    If you're introducing a publicly-facing API change that end-users will invoke and compile code against, you must increment the minor version (e.g. 0.4 -> 0.5 or 1.3 -> 1.4).

    If you're introducing an internal change that end-users cannot compile against (e.g. introducing a private class or method, or changing an existing method implementation with no signature changes) you must increment the point revision (e.g. 0.4.0 -> 0.4.1 or 1.3.1 -> 1.3.2).

    If in doubt, ask Les.

    When asked for the next development version, you can specify the next minor version and not the point revision change. It will prompt you for a point revision change, e.g. 0.8.2-SNAPSHOT. Change this to the next minor version snapshot, e.g. 0.9.0-SNAPSHOT.

    Ok, continuing on.

  2. Assuming the previous build commands did not result in errors:

    mvn release:perform

    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.

  3. Release the artifacts to the world by using the Sonatype Nexus UI

    In practice this really means the following:

    1. Visit https://oss.sonatype.org and login (upper right) using the account you created as a prerequisite.
    2. Access the 'Staging Repositories' menu item on the left
    3. Find the comstormpath-### entry - usually at the bottom - and check it.
    4. After checking the entry, at the top of the list, you will see a Close icon enabled. Click Close and type in a reason (e.g. 'closing for the 0.5.0 release') and then click the Confirm button. 'Closing' a repository prevents other artifacts from being added to it. We've never needed to do that, so closing it immediately is fine.
    5. Wait a little bit, and click the Refresh button at the top of the list. The comstormpath-### entry should still be checked.
    6. Click the Release button and type in a message, e.g 'releasing 0.8.1'. Ensure the Automatically Drop option is checked and then click the Confirm button.

    After you Confirm the Release, that's it - the artifacts will be propagated to Maven central. The sync time usually takes about 2 to 3 hours to make the artifacts available to the world.

Post Release

1. Update Project Documentation

Almost all of the Octopress Project Documentation is updated automatically.

This includes the latest API JavaDoc, Servlet Plugin and Spring Boot documentation.

The ONLY files that must be manually updated after the release are:

Follow these instructions:

# Clone [email protected]:stormpath/stormpath.github.io.git if you haven't already
git clone [email protected]:stormpath/stormpath.github.io.git
    
# Change into the doc project root directory and checkout the `source` branch:
cd stormpath.github.io
git checkout source

# Create an editing branch off of the 'source' branch (e.g. named after the release):
git checkout -b jsdk-1.0.RC5.1-release
    
# IMPORTANT: Ensure the following files reflect the latest features/changes and .jar versions:
# - source/java/product-guide/index.markdown
# - source/java/quickstart/index.markdown

In particular, the `quickstart/index.markdown` file references the release version. Make sure all occurrences are updated with the latest version, e.g. `<version>1.0.RC5.1</version>`
    
# Test that it looks good via rake generate/preview:
rake generate && rake preview
# After verifying, hit ctrl-C to exit

# If you're happy w/ the changes, commit them:
git add -A && git commit -m "Updated documentation for the Java SDK 1.0.RC5.1 release"

# merge the (now finished) editing branch back into the source branch:
git checkout source
git merge jsdk-1.0.RC5.1-release
    
# push the edits to origin:
git push

# Release the docs to the product docs web servers as documented here:
# https://stormpath.atlassian.net/wiki/display/IAMDOC/Content+Management

2. Milestone Cleanup

  • Close the milestone that represents the just-released version.

  • Add a new milestone that represents the next version to be released. Newly created issues can then have easy access to a milestone.

3. Email the Stormpath Marketing Team

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

  1. A link to the specific section in the specific tagged release's changelog.md file, e.g. https://github.com/stormpath/stormpath-sdk-java/blob/stormpath-sdk-root-1.0.RC5.1/changelog.md#10rc51. Notice that this URL points to a specific section of a specific file in a tagged release. This guarantees that this link will always work because the tag will never be changed/removed - we keep tags permanent. If you were to link to the HEAD version of the doc, it is possible that the link would break in the future. This way, we ensure that whatever link marketing uses to notify Stormpath end-users will always work in the future (e.g. in blog articles, etc).
  2. A link to the previously-verified project documentation, e.g. http://docs.stormpath.com/java/.
  3. A link to the GitHub milestone containing all issues that were resolved for the release, e.g. https://github.com/stormpath/stormpath-sdk-java/issues?q=milestone%3A1.0.RC5.1+is%3Aclosed

Example email template:

Subject: Stormpath Java SDK 1.0.RC5.1 Released!
Body:

Hi everyone,

I am pleased to announce that version 1.0.RC5.1 of the Stormpath Java SDK has been released!

This is a bugfix point release that resolves 9 issues: https://github.com/stormpath/stormpath-sdk-java/issues?q=milestone%3A1.0.RC5.1+is%3Aclosed    
Project documentation is here: http://docs.stormpath.com/java/product-guide/
Change log for 1.0.RC5.1 is here: https://github.com/stormpath/stormpath-sdk-java/blob/stormpath-sdk-root-1.0.RC5.1/changelog.md#10rc51

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

Cheers,

Your Name
Clone this wiki locally