Semantic Versioning with Jreleaser and Upcoming4j

While working with semantic-release npm package to fully automate application releases in Nodejs, I got used to an out-of-the-box workflow where conventional commits drive version calculation, git tagging, changelog generation, GitHub releases, and CI-safe publishing.

When I switched to gradle-java projects, I could not find an equivalent solution. After researching the ecosystem, Jreleaser stood out as the most complete tool available for creating Git tags, generating changelogs, and publishing GitHub releases. However, it expects the version to be predefined.

That gap led me to create Upcoming4j, a lightweight gradle plugin focused solely on semantic version calculation, designed to integrate seamlessly with Jreleaser to fully automate software versioning.

In the following step-by-step guide, I will show how to integrate JReleaser and Upcoming4j to automatically increment version numbers, create Git tags, generate changelogs, and publish GitHub releases based on Git commit history using semantic versioning.

Prerequisites

• Install Sdkman

• Install JDK 21
  

$ sdk install java 21.0.9-amzn
$ java --version

• Install git

$ brew install git
$ git --version

Step 1: Download Playground Gradle-Java Project u4j-playground

Download and unzip the playground project into your local file system. This is a gradle-java project that will be used to demonstrate how to integrate JReleaser and Upcoming4j in practice.

Step 2: Install and Configure Jreleaser Plugin

• JReleaser uses a hosted Git repository to create Git tags and publish releases. Create a new repository on your GitHub account and follow the instructions to link your local playground project to the remote repository.

• Download the Jreleaser Configuration file, and place it in the following location: /u4j-playground/gradle/jreleaser.gradle.

• Open the /u4j-playground/build.gradle file to install and apply Jreleaser configuration. The file should look like this now:
  

plugins {
    id 'application'
    // install JReleaser plugin
    id 'org.jreleaser' version '1.22.0'
}

// Apply JReleaser configuration
apply from: 'gradle/jreleaser.gradle'

// Set a harcoded version for now
version = '1.0.0'

repositories {
    mavenCentral()
}

dependencies {
    testImplementation libs.junit.jupiter
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
    implementation libs.guava
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

application {
    mainClass = 'org.example.App'
}

tasks.named('test') {
    useJUnitPlatform()
}

Step 4: Verify Jreleaser Configuration

• Create a Personal Access Token in Github, and export the token using the following environment variable:

$ export JRELEASER_GITHUB_TOKEN=your_token

• Run JReleaser in --dryrun mode to preview the release steps without making any changes:

$ ./gradlew clean jreleaserRelease --no-configuration-cache --stacktrace --dryrun

• Check logs to verify outcomes:

Notice that even in --dryrun mode, Jreleaser requires PAT being exported.

Notice that JReleaser is not yet fully compliant with Gradle’s configuration cache. Therefore --no-configuration-cache flag is being used.

Step 5: Install and Apply Upcoming4j Plugin

Open /u4j-playground/build.gradle file and install Upcoming4j plugin, the file should look like this now:

plugins {
    id 'application'
    // install JReleaser plugin
    id 'org.jreleaser' version '1.22.0'
    // Install Upcoming4j plugin
    id 'io.github.sttamper.upcoming4j' version '0.0.4'
}

// Apply JReleaser configuration
apply from: 'gradle/jreleaser.gradle'

// Set up next version with Upcoming4j
version = nx()

repositories {
    mavenCentral()
}

dependencies {
    testImplementation libs.junit.jupiter
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
    implementation libs.guava
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

application {
    mainClass = 'org.example.App'
}

tasks.named('test') {
    useJUnitPlatform()
}

Step 5: Verify Upcoming4j Configuration

Upcoming4j computes the next semantic version during Gradle’s configuration phase, ensuring that the correct version is always available in the version property of the build.gradle file.

• Clean project:

 ./gradlew clean

• Check Upcoming4j logs to confirm version calculation:

Final Step: Bump The Next Semantic Version

Now you can run JReleaser to create the next release version calculated by Upcoming4j, based on the analysis of the commit history:

./gradlew clean jreleaserRelease --no-configuration-cache --stacktrace