Skip to content

Centralized Semantic Versioning System Walkthrough

Summary

Implemented a unified, Git-tag driven Semantic Versioning (Major.Minor.Patch) system across all submodules in the cis-api-uam multi-module project. All submodules (cis-api, cis-auth, cis-bff, cis-workflow, cis-search, cis-emailer) now share the exact same version derived dynamically from Git release tags, with automatic snapshot incrementation, CI/CD override support, and complete offline capability.


What Changed

1. Versioning Engine (gradle/versioning.gradle)

Created a native Groovy resolution script plugin (zero third-party Gradle plugin dependencies): - Resolution Hierarchy: 1. -PversionOverride or -Pversion (CLI / build flag override) 2. CIS_APP_VERSION or APP_VERSION (Environment variable override) 3. Git Describe: git describe --tags --always --long - Exact tag match (v2.0.0-0-g...): Resolves to release version 2.0.0. - Commits ahead of tag (v2.0.0-5-g...): Automatically increments patch and appends -SNAPSHOT (e.g. 2.0.1-SNAPSHOT). 4. Fallback from gradle.properties: defaultVersion=2.0.0-SNAPSHOT - Helper Tasks: - :printVersion: Clean output for scripts, CI pipelines, and Docker image tags (./gradlew printVersion -q). - :showVersionDetails: Displays complete diagnostic metadata (resolved version, git describe, commit hash, active branch, group, and submodules).

2. Multi-Module Project Configuration (build.gradle)

  • Applied gradle/versioning.gradle at root level.
  • Replaced hardcoded version = '0.0.1-SNAPSHOT' with:
    allprojects {
        group = 'com.dw.ngms'
        version = rootProject.ext.resolvedAppVersion
        ...
    }
    
  • Configured all Jar tasks across submodules to inject standard manifest attributes:
  • Implementation-Title
  • Implementation-Version
  • Built-By
  • Build-Timestamp

3. Baseline Tag

Created the major version baseline annotated tag: - Git Tag: v2.0.0 - Commit: 92b8162cd (feat(build): implement centralized Git-tag based Semantic Versioning across all submodules)


Verification Results

1. Version Resolution

./gradlew showVersionDetails -q --offline
Output:
==========================================================
 CIS-API-UAM Centralized Version Details
==========================================================
 Resolved Version : 2.0.0
 Git Describe     : v2.0.0-0-g92b8162cd
 Git Commit Hash  : 92b8162cd
 Git Branch       : feature/cis-auth-bff
 Group            : com.dw.ngms
 Submodules       : cis-api, cis-auth, cis-bff, cis-emailer, cis-search, cis-workflow
==========================================================

2. All Submodules Share Identical Version

./gradlew -q --offline :cis-api:properties :cis-workflow:properties :cis-auth:properties :cis-bff:properties :cis-search:properties :cis-emailer:properties | Select-String "version:"
Output: - cis-api: version: 2.0.0 - cis-workflow: version: 2.0.0 - cis-auth: version: 2.0.0 - cis-bff: version: 2.0.0 - cis-search: version: 2.0.0 - cis-emailer: version: 2.0.0

3. Property Override

./gradlew printVersion -q "-PversionOverride=2.5.0" --offline
# Output: 2.5.0

4. Jar Artifact Generation & Manifest

Built :cis-emailer:jar producing cis-emailer-2.0.0.jar with manifest:

Manifest-Version: 1.0
Implementation-Title: cis-emailer
Implementation-Version: 2.0.0
Built-By: TEST
Build-Timestamp: 2026-11-13T12:08:28.420061400Z