Skip to content

Home

Jump to bottom Edit New page
lhazlewood edited this page Jan 29, 2024 · 23 revisions

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. Ensure all version references (dependency declarations, etc) in README.md have been replaced with the version you are about to release. 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 the same username and password you use to login to both 
                https://issues.sonatype.org and https://oss.sonatype.org.
            --> 
            <username>YOUR_OSSRH_USERNAME</username>
            <password>YOUR_OSSRH_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.

Add a custom footer
Add a custom sidebar
Clone this wiki locally