-
Notifications
You must be signed in to change notification settings - Fork 155
Release Guide
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.
-
JDK 7 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.3.9+ 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 isgpg2
and notgpg
). -
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 isCommunity Support - Open Source Project Repository Hosting (OSSRH)
. -
The
Issue Type
should be set toNew Project
-
For the
Summary
field, enter:requesting deploy rights for com.stormpath groupId
-
The
Group Id
field should be set tocom.stormpath
-
The
Project URL
andSCM url
fields should both be set tohttps://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>
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.
-
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, 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 release branch right before you perform the release.
-
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.
-
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.
-
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: 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:
As of September 2016 we have decided that from now on our master branch will always hop to minor versions:
1.0.0
->1.1.0
->1.2.0
, etc. Therefore, if current version inmaster
is1.1.0-SNAPSHOT
, the next version during the release (frommaster
) will be1.2.0-SNAPSHOT
.When asked for the next development version, Maven will assume and prompt for a point revision change, e.g.
0.8.2-SNAPSHOT
when current is0.8.1-SNAPSHOT
. Therefore be sure to manually introduce the next minor version overlooking the suggested point one.If in doubt, ask Les.
Ok, continuing on.
-
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.
-
Release the artifacts to the world by using the Sonatype Nexus UI
In practice this really means the following:
- Visit https://oss.sonatype.org and login (upper right) using the account you created as a prerequisite.
- Access the 'Staging Repositories' menu item on the left
- Find the
comstormpath-###
entry - usually at the bottom - and check it. - After checking the entry, at the top of the list, you will see a
Close
icon enabled. ClickClose
and type in a reason (e.g. 'closing for the 0.5.0 release') and then click theConfirm
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. - Wait a little bit, and click the
Refresh
button at the top of the list. Thecomstormpath-###
entry should still be checked. - Click the
Release
button and type in a message, e.g 'releasing 0.8.1'. Ensure theAutomatically Drop
option is checked and then click theConfirm
button.
After you
Confirm
theRelease
, 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.
Project Documentation update is now fully automated.
-
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.
-
Create a PR to merge the release branch into master.
-
If necessary, create a branch for the next version (e.g. 1.1.x) from the release tag.
Notify them about the release. The email should contain the following:
- 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.1.0/changelog.md#110. 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 theHEAD
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). - A link to the previously-verified project documentation, e.g. http://docs.stormpath.com/java/.
- 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?utf8=%E2%9C%93&q=milestone%3A1.1.0%20is%3Aclosed%20is%3Aissue
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 7 issues: https://github.com/stormpath/stormpath-sdk-java/issues?q=milestone%3A1.0.RC5.1+is%3Aclosed+is%3Aissue
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
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.
-
create a branch off the last release commit
git branch <branchname> <sha1-of-commit>
-
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
-
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.
-
Once the release is complete, you can merge master into your branch and then merge into master.
Please NOTE: This is somewhat delicate and best done with a partner. You will need to force-push master, and that should never be done lightly. You should only do this if you are confident that no one has merged master
into a branch after the release commit and release tag were made.
This presumes that you have not already clicked the Release
button in sonatype
. If you have, then you must publish a new release to fix whatever is wrong.
mvn release:rollback
- Check that the pom files in Github have been rolled back
-
git push --delete origin <TAG_NAME>
(usually something likestormpath-sdk-root-XX
, where XX is the release version) -
git tag -d <TAG_NAME>
(same as above): removes local tag - 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.
In the Java SDK project, make note of the commit BEFORE the release commits. Also make note of the release tag.
[![rollback][1]][1] [1]: images/StormpathRollback.png
In this case, it's dac4d48
and stormpath-sdk-root-1.0.RC5.1
.
Execute the following:
git tag -d <tag name> # delete the local tag
git push origin :refs/tags/<tag name> # delete the remote tag
git reset --hard <commit hash prior to release>
git push --force origin master
If you had gotten as far as the documentation being auto-deployed, you will need to roll that back as well in the stormpath.github.io
project following a similar procedure, except that you will be working on the source
and master
branches.
In the stormpath.github.io
project, execute the following:
git checkout source
git reset --hard <commit prior to release>
git push --force origin source
git checkout master
git reset --hard <commit prior to release>
git push --force origin master
Pushing to master
will cause the docs to refresh on the live site.
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
Be sure you are using Maven version 3.3.9+