语义化版本控制与 Jreleaser 和 Upcoming4j

Source: Dev.to

在使用 semantic-release npm 包 完全自动化 Node.js 应用发布时，我已经习惯了一套开箱即用的工作流，其中 conventional commits 驱动版本计算、git 打标签、变更日志生成、GitHub Release，以及 CI 安全的发布。

当我转向 Gradle‑Java 项目时，找不到等价的解决方案。经过对生态系统的调研，JReleaser 脱颖而出，成为在创建 Git 标签、生成变更日志和发布 GitHub Release 方面最完整的工具。但它要求版本必须预先定义。

于是我创建了 Upcoming4j，这是一款轻量级的 Gradle 插件，专注于语义化版本号计算，旨在与 JReleaser 无缝集成，实现软件版本的全自动化。

在下面的分步指南中，我将展示如何集成 JReleaser 与 Upcoming4j，实现基于 Git 提交历史的语义化版本自动化，包括：

• 增加版本号
• 创建 Git 标签
• 生成变更日志
• 发布 GitHub Release

——全部基于语义化版本的 Git 提交历史。

先决条件

• 安装 Sdkman

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

• 安装 Git

  $ brew install git
  $ git --version

第一步：下载 Playground Gradle‑Java 项目 u4j‑playground

下载并解压 the playground project 到本地文件系统。这是一个 Gradle‑Java 项目，将用于演示如何在实践中集成 JReleaser 和 Upcoming4j。

第 2 步：安装并配置 JReleaser 插件

1. 创建一个 GitHub 仓库 并将本地 playground 项目链接到远程仓库。

2. 从 this gist 下载 JReleaser 配置文件 并放置在：

   /u4j-playground/gradle/jreleaser.gradle

3. 在 /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()
   }

第4步：验证 JReleaser 配置

1. 在 GitHub 中创建个人访问令牌（PAT）并导出它：

   $ export JRELEASER_GITHUB_TOKEN=your_token

2. 在 dry‑run 模式下运行 JReleaser，以预览发布步骤而不进行任何更改：

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

3. 检查日志（示例截图）：

   

注意： 即使在 --dryrun 模式下，JReleaser 仍需要导出 PAT。
注意： JReleaser 仍未完全兼容 Gradle 的配置缓存，因此需要使用 --no-configuration-cache 标志。

第 5 步：安装并应用 Upcoming4j 插件

编辑 /u4j-playground/build.gradle，添加 Upcoming4j 插件并用 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'
}

现在，项目的版本将自动根据提交历史计算，使 JReleaser 在创建标签、变更日志和 GitHub 发布时使用正确的版本。

后续步骤

1. 提交几条符合约定的提交（例如 feat: add new feature、fix: correct typo）。

2. 运行完整的发布命令：

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

3. 验证是否已创建带有正确语义化版本的 Git 标签、变更日志条目和 GitHub 发布。

尽情享受针对 Gradle‑Java 项目的全自动、语义化版本驱动的发布吧！

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

步骤 5：验证 Upcoming4j 配置

Upcoming4j 在 Gradle 的配置阶段计算下一个语义版本，确保在 build.gradle 文件的 version 属性中始终可用正确的版本。

清理项目

./gradlew clean

• 检查 Upcoming4j 日志以确认版本计算：

  

最后一步：提升下一个语义版本

现在您可以运行 JReleaser 来创建由 Upcoming4j 计算的下一个发布版本，基于提交历史的分析：

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