Semantic Versioning with Jreleaser and Upcoming4j

Source: Dev.to

While working with the semantic-release npm package to fully automate application releases in Node.js, 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
• Publish GitHub releases

—all based on Git commit history using semantic versioning.

Prerequisites

• Install Sdkman

  $ 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

1. Create a GitHub repository and link your local playground project to the remote repository.

2. Download the JReleaser configuration file from this gist and place it at:

   /u4j-playground/gradle/jreleaser.gradle

3. Apply the configuration in /u4j-playground/build.gradle:

   plugins {
       id 'application'
       // install JReleaser plugin
       id 'org.jreleaser' version '1.22.0'
   }
   
   // Apply JReleaser configuration
   apply from: 'gradle/jreleaser.gradle'
   
   // Set a hard‑coded 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

1. Create a Personal Access Token (PAT) in GitHub and export it:

   $ export JRELEASER_GITHUB_TOKEN=your_token

2. Run JReleaser in dry‑run mode to preview the release steps without making any changes:

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

3. Check the logs (example screenshot):

   

Note: Even in --dryrun mode, JReleaser requires the PAT to be exported.
Note: JReleaser is not yet fully compatible with Gradle’s configuration cache, so the --no-configuration-cache flag is required.

Step 5: Install and Apply Upcoming4j Plugin

Edit /u4j-playground/build.gradle to add the Upcoming4j plugin and replace the hard‑coded version with the dynamic version calculated by Upcoming4j:

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'
}

Now the project’s version will be automatically calculated from the commit history, allowing JReleaser to use the correct version when creating tags, changelogs, and GitHub releases.

Next Steps

1. Commit a few conventional‑style commits (e.g., feat: add new feature, fix: correct typo).

2. Run the full release command:

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

3. Verify that a new Git tag, changelog entry, and GitHub release have been created with the correct semantic version.

Enjoy fully automated, semantic‑version‑driven releases for your Gradle‑Java projects!

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