Home

Welcome to the jjwt wiki!

Release Instructions:

1. Create a staging branch where release changes will be made. Once the release is successful, this staging branch will be merged into the master branch. For example, if master is at 0.11.4-SNAPSHOT, then we'll be making a 0.11.4 release, so we want to create a 0.11.4-staging branch to represent these changes:

   git checkout master && git pull
   git checkout -b 0.11.4-staging
   git push -u origin # push the new 0.11.4-staging branch to the remote origin server (i.e. GitHub)

2. Ensure all @since JJWT_RELEASE_VERSION references are changed to the version you are about to release. Commit/push these changes to the staging branch.

3. Edit the project root README.adoc file: at the top of the file, change the :project-version: document header attribute value to the version you are about to release (e.g. 0.11.4). Commit/push this change to the staging branch.

4. Ensure that CHANGELOG.md has a section for the specific release version (e.g. 0.11.4) that explains why the release was created. Be careful to ensure a link to the GitHub release as well as a backwards-compatibility section if anything was introduced that was incompatible. Commit/push this change to the staging branch.

5. Squash all changes to a single commit and push to origin:

   git rebase -i origin/master # resolve any conflicts and commit
   git push -u origin --force # push to origin

6. Ensure that the squashed commit builds in CI successfully:

   gh workflow run CI --ref "$STAGING_BRANCH_ID"

   Where STAGING_BRANCH_ID is the staging branch created above (e.g. 0.11.4-staging).

   If it does, we can move on to the actual release next.

7. Ensure the correct ~/.m2/settings.xml are enabled (not using a company private repo) and you have both the ossrh profile and ossrh server enabled as follows:

   <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
   
       <profiles>
           <profile>
               <id>ossrh</id>
               <properties>
                   <!-- 
                       All artifacts uploaded to Nexus/OSSRH for release must be verified via digital signatures, 
                       so configure gpg (or gpg2) for signing with a gpg key.  More information can be found here: 
                       https://central.sonatype.org/publish/requirements/gpg/
                   -->
                   <gpg.executable>gpg</gpg.executable> <!-- or gpg2 if that's what you have installed -->
                   <gpg.keyname>YOUR_GPG_KEY_ID</gpg.keyname>
                   <gpg.passphrase>YOUR_GPG_KEY_PASSPHRASE</gpg.passphrase>
               </properties>
           </profile>
           <!-- ... any other profiles you may have for your own needs ... -->
       </profiles>
   
       <servers>
           <server>
               <id>ossrh</id>
               <!--
                   This is NOT the username/password you use to login to 
                   https://oss.sonatype.org.  It is your User Token accessible
                   by logging in to oss.sonatype.org, clicking your
                   username in the upper right hand corner, choosing "profile",
                   then in the resulting view, select the "Summary" drop down 
                   and choose "User Token", then click the "Access User Token"
                   button.
               --> 
               <username>YOUR_OSSRH_ACCESS_TOKEN_USERNAME</username>
               <password>YOUR_OSSRH_ACCESS_TOKEN_PASSWORD</password>
           </server>
           <!-- ... any other servers you may have for your own needs ... -->
       </servers>
   
   </settings>

8. Ensure you have the Zulu JDK 7 installed. Yes, it must be a later Zulu 7 distribution: the only public Oracle JDK 7 release available is 1.7.0_80, and that release doesn't have TLS protocol support necessary for communicating with the Nexus OSSRH server to publish our release artifacts. The later Zulu JDK 7 builds (e.g. u342) do have the necessary backport fixes to allow a successful release deployment.

9. Ensure java -version equals this Zulu JDK 7, e.g. the output looks something like this:

   openjdk version "1.7.0_342"
   OpenJDK Runtime Environment (Zulu 7.54.0.13-CA-macosx) (build 1.7.0_342-b01)
   OpenJDK 64-Bit Server VM (Zulu 7.54.0.13-CA-macosx) (build 24.342-b01, mixed mode)

10. Ensure Maven 3.8.8 is installed and being used (3.8.8 is the last version that works with JDK 7):

    $ mvn -version
    Apache Maven 3.8.8 (4c87b05d9aedce574290d1acc98575ed5eb6cd39)
    Maven home: /Users/lhazlewood/.sdkman/candidates/maven/current
    Java version: 1.7.0_352, vendor: Azul Systems, Inc., runtime: /Users/lhazlewood/.sdkman/candidates/java/7.0.352b01-zulu/zulu-7.jdk/Contents/Home/jre
    Default locale: en_US, platform encoding: UTF-8
    OS name: "mac os x", version: "10.16", arch: "x86_64", family: "mac"

11. Ensure MAVEN_OPTS is set properly:

    export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m"

12. Run the release build:

    mvn clean
    mvn release:clean
    mvn release:prepare
    # Choose a version number.
    # Choose an SCM release tag.  This should be *just* the version number: 0.5, not jjwt-0.5
    # Choose the new development version.  If releasing 0.5, this would be 0.6-SNAPSHOT
    mvn release:perform

13. In the master branch (and in the Maj.min.x branch if you are cutting a patch release), change the root pom.xml jjwt.previousVersion property value to equal the version just released. Commit and push these changes.

14. Log in to the Sonatype OSSRH admin console

15. On the menu on the left, click the Staging Repositories link. On the resulting list, find iojsonwebtoken-### (usually at the bottom of the list). Check the checkbox for that item.

16. Click the Close button at the top of the list. Add in a quick note (e.g. 'Closing for the 0.5 release') and click Confirm.

17. Wait a minute or so and click the Refresh button at the top of the list. The Release button should now be enabled. Click Release and enter in a quick note (e.g. 'Releasing 0.5'). Ensure the Automatically Drop option IS checked (you want this). Click Confirm.

18. Logout.

19. Squash and merge the staging branch (e.g. 0.11.4-staging as a Pull Request into master to ensure mainline development receives all staging changes.

20. Create a new GitHub release and:

    1. Choose the just-released tag.
    2. Provide plenty of release notes in the description, copy over what's in the CHANGELOG.md file if necessary. This is beneficial because people subscribe to release notifications and can be easily notified automatically.
    3. Attach the maven binaries? (.jar, src .jar, javadoc .jar, etc?)
    4. Click the 'Create a discussion for this release' checkbox.

21. Publish a Tweet to announce the release. For example: https://twitter.com/lhazlewood/status/1225170466295271425

That's it! The release should show up in Maven Central in 15 to 30 minutes.