Semantic Versioning (SemVer) is a versioning scheme that provides meaning to version numbers, helping communicate the nature of changes between releases. This guide covers implementing SemVer parsing, validation, and automation in Java applications.

Core Concepts

Semantic Versioning Format:

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Version Components:

• MAJOR: Incompatible API changes
• MINOR: Backward-compatible new functionality
• PATCH: Backward-compatible bug fixes
• PRERELEASE: Pre-release versions (alpha, beta, rc)
• BUILD: Build metadata (ignored in version comparisons)

Dependencies and Setup

Maven Dependencies

<properties> <spring-boot.version>3.1.0</spring-boot.version> <maven-plugin-api.version>3.9.5</maven-plugin-api.version> </properties> <dependencies> <!-- Spring Boot (for web applications) --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>${spring-boot.version}</version> <optional>true</optional> </dependency> <!-- Maven Plugin API (for Maven integration) --> <dependency> <groupId>org.apache.maven</groupId> <artifactId>maven-plugin-api</artifactId> <version>${maven-plugin-api.version}</version> <optional>true</optional> </dependency> <!-- Testing --> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> <version>5.9.2</version> <scope>test</scope> </dependency> </dependencies>

Core Implementation

1. Semantic Version Model

public class SemanticVersion implements Comparable<SemanticVersion> { private final int major; private final int minor; private final int patch; private final String preRelease; private final String buildMetadata; private static final Pattern SEMVER_PATTERN = Pattern.compile( "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)" + "(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?" + "(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$" ); public SemanticVersion(int major, int minor, int patch) { this(major, minor, patch, null, null); } public SemanticVersion(int major, int minor, int patch, String preRelease, String buildMetadata) { if (major < 0 || minor < 0 || patch < 0) { throw new IllegalArgumentException("Version components cannot be negative"); } validatePreRelease(preRelease); validateBuildMetadata(buildMetadata); this.major = major; this.minor = minor; this.patch = patch; this.preRelease = preRelease; this.buildMetadata = buildMetadata; } public static SemanticVersion of(String version) { if (version == null || version.trim().isEmpty()) { throw new IllegalArgumentException("Version string cannot be null or empty"); } Matcher matcher = SEMVER_PATTERN.matcher(version.trim()); if (!matcher.matches()) { throw new IllegalArgumentException("Invalid semantic version: " + version); } int major = Integer.parseInt(matcher.group(1)); int minor = Integer.parseInt(matcher.group(2)); int patch = Integer.parseInt(matcher.group(3)); String preRelease = matcher.group(4); String buildMetadata = matcher.group(5); return new SemanticVersion(major, minor, patch, preRelease, buildMetadata); } private void validatePreRelease(String preRelease) { if (preRelease == null || preRelease.isEmpty()) { return; } String[] identifiers = preRelease.split("\\."); for (String identifier : identifiers) { if (identifier.isEmpty()) { throw new IllegalArgumentException("Pre-release identifier cannot be empty"); } // Check if identifier is numeric-only if (identifier.matches("\\d+")) { // Numeric identifiers must not contain leading zeros if (identifier.length() > 1 && identifier.startsWith("0")) { throw new IllegalArgumentException("Numeric pre-release identifier cannot have leading zeros: " + identifier); } } else { // Non-numeric identifiers should be alphanumeric with hyphens if (!identifier.matches("[0-9A-Za-z-]+")) { throw new IllegalArgumentException("Invalid pre-release identifier: " + identifier); } } } } private void validateBuildMetadata(String buildMetadata) { if (buildMetadata == null || buildMetadata.isEmpty()) { return; } String[] identifiers = buildMetadata.split("\\."); for (String identifier : identifiers) { if (identifier.isEmpty()) { throw new IllegalArgumentException("Build metadata identifier cannot be empty"); } if (!identifier.matches("[0-9A-Za-z-]+")) { throw new IllegalArgumentException("Invalid build metadata identifier: " + identifier); } } } // Getters public int getMajor() { return major; } public int getMinor() { return minor; } public int getPatch() { return patch; } public String getPreRelease() { return preRelease; } public String getBuildMetadata() { return buildMetadata; } public boolean isPreRelease() { return preRelease != null && !preRelease.isEmpty(); } public boolean isStable() { return !isPreRelease(); } public String getVersion() { StringBuilder sb = new StringBuilder(); sb.append(major).append('.').append(minor).append('.').append(patch); if (preRelease != null && !preRelease.isEmpty()) { sb.append('-').append(preRelease); } if (buildMetadata != null && !buildMetadata.isEmpty()) { sb.append('+').append(buildMetadata); } return sb.toString(); } @Override public String toString() { return getVersion(); } @Override public boolean equals(Object o) { if (this == o) return true; if (o == null || getClass() != o.getClass()) return false; SemanticVersion that = (SemanticVersion) o; return major == that.major && minor == that.minor && patch == that.patch && Objects.equals(preRelease, that.preRelease); // Build metadata is ignored in equality check } @Override public int hashCode() { return Objects.hash(major, minor, patch, preRelease); } @Override public int compareTo(SemanticVersion other) { if (other == null) return 1; // Compare major, minor, patch int result = Integer.compare(major, other.major); if (result != 0) return result; result = Integer.compare(minor, other.minor); if (result != 0) return result; result = Integer.compare(patch, other.patch); if (result != 0) return result; // Pre-release versions have lower precedence if (preRelease == null && other.preRelease == null) return 0; if (preRelease == null) return 1; // No pre-release > has pre-release if (other.preRelease == null) return -1; // Has pre-release < no pre-release return comparePreRelease(preRelease, other.preRelease); } private int comparePreRelease(String pre1, String pre2) { String[] identifiers1 = pre1.split("\\."); String[] identifiers2 = pre2.split("\\."); int minLength = Math.min(identifiers1.length, identifiers2.length); for (int i = 0; i < minLength; i++) { String id1 = identifiers1[i]; String id2 = identifiers2[i]; int result = compareIdentifier(id1, id2); if (result != 0) return result; } // If all identifiers are equal, longer pre-release string has higher precedence return Integer.compare(identifiers1.length, identifiers2.length); } private int compareIdentifier(String id1, String id2) { boolean isNumeric1 = id1.matches("\\d+"); boolean isNumeric2 = id2.matches("\\d+"); if (isNumeric1 && isNumeric2) { // Compare numerically return Integer.compare(Integer.parseInt(id1), Integer.parseInt(id2)); } else if (isNumeric1) { // Numeric identifiers have lower precedence than non-numeric return -1; } else if (isNumeric2) { // Non-numeric identifiers have higher precedence than numeric return 1; } else { // Compare lexically in ASCII sort order return id1.compareTo(id2); } } // Version increment methods public SemanticVersion incrementMajor() { return new SemanticVersion(major + 1, 0, 0); } public SemanticVersion incrementMajor(String preRelease) { return new SemanticVersion(major + 1, 0, 0, preRelease, null); } public SemanticVersion incrementMinor() { return new SemanticVersion(major, minor + 1, 0); } public SemanticVersion incrementMinor(String preRelease) { return new SemanticVersion(major, minor + 1, 0, preRelease, null); } public SemanticVersion incrementPatch() { return new SemanticVersion(major, minor, patch + 1); } public SemanticVersion incrementPatch(String preRelease) { return new SemanticVersion(major, minor, patch + 1, preRelease, null); } public SemanticVersion withPreRelease(String preRelease) { return new SemanticVersion(major, minor, patch, preRelease, buildMetadata); } public SemanticVersion withBuildMetadata(String buildMetadata) { return new SemanticVersion(major, minor, patch, preRelease, buildMetadata); } public SemanticVersion withoutPreRelease() { return new SemanticVersion(major, minor, patch, null, buildMetadata); } public SemanticVersion withoutBuildMetadata() { return new SemanticVersion(major, minor, patch, preRelease, null); } // Version range checking public boolean isCompatibleWith(SemanticVersion other) { if (other == null) return false; return this.major == other.major; } public boolean isNewerThan(SemanticVersion other) { return this.compareTo(other) > 0; } public boolean isOlderThan(SemanticVersion other) { return this.compareTo(other) < 0; } }

2. Version Range Support

public class VersionRange { private final SemanticVersion minVersion; private final SemanticVersion maxVersion; private final boolean minInclusive; private final boolean maxInclusive; private static final Pattern RANGE_PATTERN = Pattern.compile( "^([\\[(])\\s*([^,\\s]+)?\\s*,\\s*([^,\\s]+)?\\s*([\\])])$" ); public VersionRange(SemanticVersion minVersion, SemanticVersion maxVersion, boolean minInclusive, boolean maxInclusive) { this.minVersion = minVersion; this.maxVersion = maxVersion; this.minInclusive = minInclusive; this.maxInclusive = maxInclusive; if (minVersion != null && maxVersion != null && minVersion.compareTo(maxVersion) > 0) { throw new IllegalArgumentException("Min version cannot be greater than max version"); } } public static VersionRange exact(SemanticVersion version) { return new VersionRange(version, version, true, true); } public static VersionRange atLeast(SemanticVersion version) { return new VersionRange(version, null, true, false); } public static VersionRange atMost(SemanticVersion version) { return new VersionRange(null, version, false, true); } public static VersionRange between(SemanticVersion min, SemanticVersion max) { return new VersionRange(min, max, true, true); } public static VersionRange of(String range) { if (range == null || range.trim().isEmpty()) { throw new IllegalArgumentException("Range string cannot be null or empty"); } String trimmed = range.trim(); // Handle exact version if (!trimmed.contains(",")) { try { SemanticVersion exact = SemanticVersion.of(trimmed); return exact(exact); } catch (IllegalArgumentException e) { // Not an exact version, try parsing as range } } Matcher matcher = RANGE_PATTERN.matcher(trimmed); if (!matcher.matches()) { throw new IllegalArgumentException("Invalid version range format: " + range); } String leftBracket = matcher.group(1); String minStr = matcher.group(2); String maxStr = matcher.group(3); String rightBracket = matcher.group(4); SemanticVersion min = minStr != null ? SemanticVersion.of(minStr) : null; SemanticVersion max = maxStr != null ? SemanticVersion.of(maxStr) : null; boolean minInclusive = "[".equals(leftBracket); boolean maxInclusive = "]".equals(rightBracket); return new VersionRange(min, max, minInclusive, maxInclusive); } public boolean contains(SemanticVersion version) { if (version == null) return false; boolean minOk = true; boolean maxOk = true; if (minVersion != null) { int cmp = version.compareTo(minVersion); minOk = minInclusive ? cmp >= 0 : cmp > 0; } if (maxVersion != null) { int cmp = version.compareTo(maxVersion); maxOk = maxInclusive ? cmp <= 0 : cmp < 0; } return minOk && maxOk; } public SemanticVersion getMinVersion() { return minVersion; } public SemanticVersion getMaxVersion() { return maxVersion; } public boolean isMinInclusive() { return minInclusive; } public boolean isMaxInclusive() { return maxInclusive; } @Override public String toString() { StringBuilder sb = new StringBuilder(); sb.append(minInclusive ? '[' : '('); if (minVersion != null) { sb.append(minVersion); } sb.append(','); if (maxVersion != null) { sb.append(maxVersion); } sb.append(maxInclusive ? ']' : ')'); return sb.toString(); } }

3. Version Management Service

@Service @Slf4j public class VersionManagementService { private final GitService gitService; private final VersionHistoryRepository versionHistoryRepository; public VersionManagementService(GitService gitService, VersionHistoryRepository versionHistoryRepository) { this.gitService = gitService; this.versionHistoryRepository = versionHistoryRepository; } public SemanticVersion determineNextVersion(VersionIncrementStrategy strategy, String currentVersion, List<CommitMessage> commitMessages) { SemanticVersion current = SemanticVersion.of(currentVersion); switch (strategy) { case MAJOR: return current.incrementMajor(); case MINOR: return current.incrementMinor(); case PATCH: return current.incrementPatch(); case AUTO: return autoDetermineNextVersion(current, commitMessages); case PRE_RELEASE: return determinePreReleaseVersion(current, commitMessages); default: throw new IllegalArgumentException("Unknown strategy: " + strategy); } } private SemanticVersion autoDetermineNextVersion(SemanticVersion current, List<CommitMessage> commitMessages) { VersionIncrement maxIncrement = VersionIncrement.PATCH; for (CommitMessage commit : commitMessages) { VersionIncrement increment = analyzeCommitType(commit); if (increment.ordinal() > maxIncrement.ordinal()) { maxIncrement = increment; } } switch (maxIncrement) { case MAJOR: return current.incrementMajor(); case MINOR: return current.incrementMinor(); case PATCH: return current.incrementPatch(); default: return current.incrementPatch(); } } private SemanticVersion determinePreReleaseVersion(SemanticVersion current, List<CommitMessage> commitMessages) { SemanticVersion baseVersion = autoDetermineNextVersion(current, commitMessages); // Get existing pre-release versions for this base List<SemanticVersion> preReleases = versionHistoryRepository .findPreReleasesForVersion(baseVersion.getMajor(), baseVersion.getMinor(), baseVersion.getPatch()); // Determine next pre-release identifier String nextPreRelease = determineNextPreReleaseIdentifier(preReleases); return baseVersion.withPreRelease(nextPreRelease); } private VersionIncrement analyzeCommitType(CommitMessage commit) { String message = commit.getMessage().toLowerCase(); // Conventional Commits pattern matching if (message.startsWith("feat:") || message.startsWith("feat(")) { return VersionIncrement.MINOR; } else if (message.startsWith("fix:") || message.startsWith("fix(")) { return VersionIncrement.PATCH; } else if (message.startsWith("break:") || message.startsWith("break(") || message.contains("breaking change")) { return VersionIncrement.MAJOR; } else if (message.startsWith("perf:") || message.startsWith("perf(")) { return VersionIncrement.PATCH; } else if (message.startsWith("refactor:") || message.startsWith("refactor(")) { return VersionIncrement.PATCH; } else if (message.startsWith("docs:") || message.startsWith("docs(")) { return VersionIncrement.NONE; } else if (message.startsWith("style:") || message.startsWith("style(")) { return VersionIncrement.NONE; } else if (message.startsWith("test:") || message.startsWith("test(")) { return VersionIncrement.NONE; } else if (message.startsWith("chore:") || message.startsWith("chore(")) { return VersionIncrement.NONE; } return VersionIncrement.PATCH; // Default to patch for unknown types } private String determineNextPreReleaseIdentifier(List<SemanticVersion> existingPreReleases) { if (existingPreReleases.isEmpty()) { return "alpha.1"; } // Find the highest numeric identifier for each pre-release type Map<String, Integer> maxIdentifiers = new HashMap<>(); for (SemanticVersion version : existingPreReleases) { String preRelease = version.getPreRelease(); if (preRelease != null) { String[] parts = preRelease.split("\\."); String type = parts[0]; if (parts.length > 1 && parts[1].matches("\\d+")) { int number = Integer.parseInt(parts[1]); maxIdentifiers.merge(type, number, Math::max); } } } // Use alpha as default type String type = "alpha"; int nextNumber = maxIdentifiers.getOrDefault(type, 0) + 1; return type + "." + nextNumber; } public VersionBumpResult bumpVersion(VersionBumpRequest request) { try { log.info("Bumping version for project: {}", request.getProjectName()); // Determine next version SemanticVersion currentVersion = SemanticVersion.of(request.getCurrentVersion()); SemanticVersion nextVersion = determineNextVersion( request.getStrategy(), request.getCurrentVersion(), request.getCommitMessages() ); // Update version files List<VersionFileUpdate> fileUpdates = updateVersionFiles( request.getProjectRoot(), currentVersion, nextVersion ); // Create Git commit String commitMessage = String.format("chore: release %s", nextVersion); String commitHash = gitService.commitChanges(commitMessage); // Create Git tag String tagName = "v" + nextVersion; gitService.createTag(tagName, commitHash); // Record version history VersionHistory history = VersionHistory.builder() .projectName(request.getProjectName()) .version(nextVersion.toString()) .commitHash(commitHash) .bumpStrategy(request.getStrategy()) .timestamp(Instant.now()) .build(); versionHistoryRepository.save(history); return VersionBumpResult.success(nextVersion.toString(), fileUpdates, commitHash, tagName); } catch (Exception e) { log.error("Failed to bump version: {}", e.getMessage(), e); return VersionBumpResult.failure(e.getMessage()); } } private List<VersionFileUpdate> updateVersionFiles(Path projectRoot, SemanticVersion currentVersion, SemanticVersion nextVersion) throws IOException { List<VersionFileUpdate> updates = new ArrayList<>(); // Update pom.xml for Maven projects Path pomPath = projectRoot.resolve("pom.xml"); if (Files.exists(pomPath)) { updateMavenVersion(pomPath, currentVersion, nextVersion); updates.add(new VersionFileUpdate("pom.xml", "Maven project version")); } // Update package.json for Node.js projects Path packageJsonPath = projectRoot.resolve("package.json"); if (Files.exists(packageJsonPath)) { updatePackageJsonVersion(packageJsonPath, currentVersion, nextVersion); updates.add(new VersionFileUpdate("package.json", "Node.js package version")); } // Update build.gradle for Gradle projects Path gradlePath = projectRoot.resolve("build.gradle"); if (Files.exists(gradlePath)) { updateGradleVersion(gradlePath, currentVersion, nextVersion); updates.add(new VersionFileUpdate("build.gradle", "Gradle project version")); } // Update version.properties for custom version files Path versionPropertiesPath = projectRoot.resolve("version.properties"); if (Files.exists(versionPropertiesPath)) { updatePropertiesVersion(versionPropertiesPath, currentVersion, nextVersion); updates.add(new VersionFileUpdate("version.properties", "Application version")); } return updates; } private void updateMavenVersion(Path pomPath, SemanticVersion currentVersion, SemanticVersion nextVersion) throws IOException { String content = Files.readString(pomPath); // Update version in <version> tags String updatedContent = content.replaceAll( "<version>" + Pattern.quote(currentVersion.toString()) + "</version>", "<version>" + nextVersion.toString() + "</version>" ); Files.writeString(pomPath, updatedContent); } private void updatePackageJsonVersion(Path packageJsonPath, SemanticVersion currentVersion, SemanticVersion nextVersion) throws IOException { String content = Files.readString(packageJsonPath); // Update version in JSON String updatedContent = content.replaceAll( "\"version\":\\s*\"" + Pattern.quote(currentVersion.toString()) + "\"", "\"version\": \"" + nextVersion.toString() + "\"" ); Files.writeString(packageJsonPath, updatedContent); } // Similar methods for Gradle and properties files... public enum VersionIncrementStrategy { MAJOR, MINOR, PATCH, AUTO, PRE_RELEASE } public enum VersionIncrement { NONE, PATCH, MINOR, MAJOR } }

4. Data Transfer Objects

@Data @Builder @NoArgsConstructor @AllArgsConstructor public class VersionBumpRequest { private String projectName; private String currentVersion; private VersionManagementService.VersionIncrementStrategy strategy; private Path projectRoot; private List<CommitMessage> commitMessages; private String branch; private boolean createTag; private boolean pushChanges; } @Data @Builder @NoArgsConstructor @AllArgsConstructor public class VersionBumpResult { private boolean success; private String message; private String newVersion; private String commitHash; private String tagName; private List<VersionFileUpdate> updatedFiles; private Instant timestamp; public static VersionBumpResult success(String newVersion, List<VersionFileUpdate> updatedFiles, String commitHash, String tagName) { return VersionBumpResult.builder() .success(true) .message("Version bumped successfully") .newVersion(newVersion) .updatedFiles(updatedFiles) .commitHash(commitHash) .tagName(tagName) .timestamp(Instant.now()) .build(); } public static VersionBumpResult failure(String error) { return VersionBumpResult.builder() .success(false) .message("Version bump failed: " + error) .timestamp(Instant.now()) .build(); } } @Data @Builder @NoArgsConstructor @AllArgsConstructor public class VersionFileUpdate { private String filename; private String description; private boolean successful; private String error; public VersionFileUpdate(String filename, String description) { this.filename = filename; this.description = description; this.successful = true; } } @Data @Builder @NoArgsConstructor @AllArgsConstructor public class CommitMessage { private String hash; private String message; private String author; private Instant timestamp; private List<String> changedFiles; } @Entity @Table(name = "version_history") @Data @Builder @NoArgsConstructor @AllArgsConstructor public class VersionHistory { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; private String projectName; private String version; private String commitHash; @Enumerated(EnumType.STRING) private VersionManagementService.VersionIncrementStrategy bumpStrategy; private Instant timestamp; private String releasedBy; @Column(length = 1000) private String releaseNotes; }

5. Git Service Integration

@Service @Slf4j public class GitService { public String commitChanges(String message) throws GitAPIException, IOException { try (Git git = Git.open(Paths.get(".").toFile())) { // Add all changes git.add().addFilepattern(".").call(); // Commit RevCommit commit = git.commit() .setMessage(message) .setAuthor("Version Bot", "[email protected]") .call(); log.info("Created commit: {} - {}", commit.getId().getName(), message); return commit.getId().getName(); } } public void createTag(String tagName, String commitHash) throws GitAPIException, IOException { try (Git git = Git.open(Paths.get(".").toFile())) { git.tag() .setName(tagName) .setObjectId(git.getRepository().resolve(commitHash)) .call(); log.info("Created tag: {}", tagName); } } public void pushChanges() throws GitAPIException, IOException { try (Git git = Git.open(Paths.get(".").toFile())) { git.push().call(); log.info("Pushed changes to remote"); } } public void pushTag(String tagName) throws GitAPIException, IOException { try (Git git = Git.open(Paths.get(".").toFile())) { git.push().setPushTags().call(); log.info("Pushed tag to remote: {}", tagName); } } public List<CommitMessage> getCommitsSince(String sinceVersion) throws GitAPIException, IOException { try (Git git = Git.open(Paths.get(".").toFile())) { String sinceTag = "v" + sinceVersion; Iterable<RevCommit> commits = git.log() .add(git.getRepository().resolve("HEAD")) .not(git.getRepository().resolve(sinceTag)) .call(); List<CommitMessage> commitMessages = new ArrayList<>(); for (RevCommit commit : commits) { CommitMessage msg = CommitMessage.builder() .hash(commit.getId().getName()) .message(commit.getFullMessage()) .author(commit.getAuthorIdent().getName()) .timestamp(commit.getAuthorIdent().getWhen().toInstant()) .build(); commitMessages.add(msg); } return commitMessages; } } }

REST API Controllers

1. Version Management API

@RestController @RequestMapping("/api/versions") @Slf4j public class VersionController { private final VersionManagementService versionService; public VersionController(VersionManagementService versionService) { this.versionService = versionService; } @PostMapping("/bump") public ResponseEntity<VersionBumpResult> bumpVersion(@RequestBody VersionBumpRequest request) { log.info("Received version bump request for project: {}", request.getProjectName()); try { VersionBumpResult result = versionService.bumpVersion(request); if (result.isSuccess()) { return ResponseEntity.ok(result); } else { return ResponseEntity.badRequest().body(result); } } catch (Exception e) { log.error("Version bump failed: {}", e.getMessage(), e); return ResponseEntity.internalServerError() .body(VersionBumpResult.failure("Internal server error: " + e.getMessage())); } } @PostMapping("/validate") public ResponseEntity<ValidationResult> validateVersion(@RequestBody VersionValidationRequest request) { try { SemanticVersion version = SemanticVersion.of(request.getVersion()); ValidationResult result = ValidationResult.builder() .valid(true) .version(version.toString()) .message("Valid semantic version") .build(); return ResponseEntity.ok(result); } catch (IllegalArgumentException e) { ValidationResult result = ValidationResult.builder() .valid(false) .version(request.getVersion()) .message("Invalid semantic version: " + e.getMessage()) .build(); return ResponseEntity.badRequest().body(result); } } @GetMapping("/compare") public ResponseEntity<VersionComparison> compareVersions( @RequestParam String version1, @RequestParam String version2) { try { SemanticVersion v1 = SemanticVersion.of(version1); SemanticVersion v2 = SemanticVersion.of(version2); int comparison = v1.compareTo(v2); String relationship; if (comparison < 0) { relationship = version1 + " is older than " + version2; } else if (comparison > 0) { relationship = version1 + " is newer than " + version2; } else { relationship = version1 + " is equal to " + version2; } VersionComparison result = VersionComparison.builder() .version1(version1) .version2(version2) .comparisonResult(comparison) .relationship(relationship) .compatible(v1.isCompatibleWith(v2)) .build(); return ResponseEntity.ok(result); } catch (IllegalArgumentException e) { return ResponseEntity.badRequest().body( VersionComparison.builder() .error("Invalid version format: " + e.getMessage()) .build() ); } } @GetMapping("/next") public ResponseEntity<NextVersionResponse> suggestNextVersion( @RequestParam String currentVersion, @RequestParam(defaultValue = "AUTO") VersionManagementService.VersionIncrementStrategy strategy, @RequestParam(required = false) String commitMessages) { try { List<CommitMessage> messages = parseCommitMessages(commitMessages); SemanticVersion nextVersion = versionService.determineNextVersion( strategy, currentVersion, messages); NextVersionResponse response = NextVersionResponse.builder() .currentVersion(currentVersion) .suggestedVersion(nextVersion.toString()) .strategy(strategy) .build(); return ResponseEntity.ok(response); } catch (Exception e) { return ResponseEntity.badRequest().body( NextVersionResponse.builder() .error(e.getMessage()) .build() ); } } private List<CommitMessage> parseCommitMessages(String commitMessages) { if (commitMessages == null || commitMessages.trim().isEmpty()) { return List.of(); } // Simple parsing - in reality, you'd parse from Git log or JSON return Arrays.stream(commitMessages.split("\n")) .map(msg -> CommitMessage.builder().message(msg).build()) .collect(Collectors.toList()); } } @Data @Builder @NoArgsConstructor @AllArgsConstructor class VersionValidationRequest { private String version; } @Data @Builder @NoArgsConstructor @AllArgsConstructor class ValidationResult { private boolean valid; private String version; private String message; } @Data @Builder @NoArgsConstructor @AllArgsConstructor class VersionComparison { private String version1; private String version2; private int comparisonResult; private String relationship; private Boolean compatible; private String error; } @Data @Builder @NoArgsConstructor @AllArgsConstructor class NextVersionResponse { private String currentVersion; private String suggestedVersion; private VersionManagementService.VersionIncrementStrategy strategy; private String error; }

2. Version History API

@RestController @RequestMapping("/api/version-history") @Slf4j public class VersionHistoryController { private final VersionHistoryRepository historyRepository; public VersionHistoryController(VersionHistoryRepository historyRepository) { this.historyRepository = historyRepository; } @GetMapping("/{projectName}") public ResponseEntity<List<VersionHistory>> getVersionHistory(@PathVariable String projectName) { List<VersionHistory> history = historyRepository.findByProjectNameOrderByTimestampDesc(projectName); return ResponseEntity.ok(history); } @GetMapping("/{projectName}/latest") public ResponseEntity<VersionHistory> getLatestVersion(@PathVariable String projectName) { return historyRepository.findTopByProjectNameOrderByTimestampDesc(projectName) .map(ResponseEntity::ok) .orElse(ResponseEntity.notFound().build()); } @PostMapping("/{projectName}") public ResponseEntity<VersionHistory> recordVersionRelease( @PathVariable String projectName, @RequestBody ReleaseVersionRequest request) { VersionHistory history = VersionHistory.builder() .projectName(projectName) .version(request.getVersion()) .commitHash(request.getCommitHash()) .bumpStrategy(request.getStrategy()) .releasedBy(request.getReleasedBy()) .releaseNotes(request.getReleaseNotes()) .timestamp(Instant.now()) .build(); VersionHistory saved = historyRepository.save(history); return ResponseEntity.status(HttpStatus.CREATED).body(saved); } } @Data @NoArgsConstructor @AllArgsConstructor class ReleaseVersionRequest { private String version; private String commitHash; private VersionManagementService.VersionIncrementStrategy strategy; private String releasedBy; private String releaseNotes; }

Maven Plugin Integration

1. Semantic Version Maven Plugin

@Mojo(name = "bump-version", defaultPhase = LifecyclePhase.VALIDATE) public class VersionBumpMojo extends AbstractMojo { @Parameter(property = "bumpStrategy", defaultValue = "AUTO") private String bumpStrategy; @Parameter(property = "createTag", defaultValue = "true") private boolean createTag; @Parameter(property = "pushChanges", defaultValue = "false") private boolean pushChanges; @Parameter(property = "project", required = true, readonly = true) private MavenProject project; @Override public void execute() throws MojoExecutionException, MojoFailureException { getLog().info("Bumping version using strategy: " + bumpStrategy); try { VersionManagementService versionService = createVersionService(); VersionBumpRequest request = VersionBumpRequest.builder() .projectName(project.getArtifactId()) .currentVersion(project.getVersion()) .strategy(VersionManagementService.VersionIncrementStrategy.valueOf(bumpStrategy.toUpperCase())) .projectRoot(project.getBasedir().toPath()) .createTag(createTag) .pushChanges(pushChanges) .build(); VersionBumpResult result = versionService.bumpVersion(request); if (result.isSuccess()) { getLog().info("Successfully bumped version to: " + result.getNewVersion()); // Update Maven project version project.setVersion(result.getNewVersion()); } else { throw new MojoFailureException("Version bump failed: " + result.getMessage()); } } catch (Exception e) { throw new MojoExecutionException("Failed to bump version", e); } } private VersionManagementService createVersionService() { // Create service instance with dependencies return new VersionManagementService(new GitService(), new InMemoryVersionHistoryRepository()); } }

2. Plugin Configuration in pom.xml

<build> <plugins> <plugin> <groupId>com.example</groupId> <artifactId>semantic-version-maven-plugin</artifactId> <version>1.0.0</version> <configuration> <bumpStrategy>AUTO</bumpStrategy> <createTag>true</createTag> <pushChanges>false</pushChanges> </configuration> </plugin> </plugins> </build>

Testing

1. Unit Tests

class SemanticVersionTest { @Test void shouldParseValidSemanticVersion() { // Given String versionString = "1.2.3"; // When SemanticVersion version = SemanticVersion.of(versionString); // Then assertThat(version.getMajor()).isEqualTo(1); assertThat(version.getMinor()).isEqualTo(2); assertThat(version.getPatch()).isEqualTo(3); assertThat(version.isPreRelease()).isFalse(); assertThat(version.toString()).isEqualTo("1.2.3"); } @Test void shouldParseVersionWithPreRelease() { // Given String versionString = "1.2.3-alpha.1"; // When SemanticVersion version = SemanticVersion.of(versionString); // Then assertThat(version.getMajor()).isEqualTo(1); assertThat(version.getMinor()).isEqualTo(2); assertThat(version.getPatch()).isEqualTo(3); assertThat(version.getPreRelease()).isEqualTo("alpha.1"); assertThat(version.isPreRelease()).isTrue(); } @Test void shouldCompareVersionsCorrectly() { // Given SemanticVersion v1 = SemanticVersion.of("1.2.3"); SemanticVersion v2 = SemanticVersion.of("1.2.4"); SemanticVersion v3 = SemanticVersion.of("1.2.3-alpha"); // Then assertThat(v1).isLessThan(v2); assertThat(v3).isLessThan(v1); assertThat(v1).isEqualTo(SemanticVersion.of("1.2.3")); } @Test void shouldIncrementVersions() { // Given SemanticVersion version = SemanticVersion.of("1.2.3"); // When SemanticVersion major = version.incrementMajor(); SemanticVersion minor = version.incrementMinor(); SemanticVersion patch = version.incrementPatch(); // Then assertThat(major).isEqualTo(SemanticVersion.of("2.0.0")); assertThat(minor).isEqualTo(SemanticVersion.of("1.3.0")); assertThat(patch).isEqualTo(SemanticVersion.of("1.2.4")); } @Test void shouldRejectInvalidVersions() { assertThatThrownBy(() -> SemanticVersion.of("1.2")) .isInstanceOf(IllegalArgumentException.class); assertThatThrownBy(() -> SemanticVersion.of("1.2.3.4")) .isInstanceOf(IllegalArgumentException.class); assertThatThrownBy(() -> SemanticVersion.of("1.2.3-01")) .isInstanceOf(IllegalArgumentException.class); } } @SpringBootTest class VersionManagementServiceTest { @Autowired private VersionManagementService versionService; @Test void shouldDetermineNextVersionBasedOnCommits() { // Given List<CommitMessage> commits = Arrays.asList( CommitMessage.builder().message("feat: add new API endpoint").build(), CommitMessage.builder().message("fix: resolve null pointer exception").build() ); // When SemanticVersion nextVersion = versionService.determineNextVersion( VersionManagementService.VersionIncrementStrategy.AUTO, "1.2.3", commits ); // Then - should bump minor because of feature commit assertThat(nextVersion).isEqualTo(SemanticVersion.of("1.3.0")); } }

Best Practices

1. Configuration

# application.yml version: management: auto-bump: true create-tags: true push-changes: false default-strategy: AUTO pre-release-types: - alpha - beta - rc commit-types: major: - "break:" - "breaking change" minor: - "feat:" patch: - "fix:" - "perf:" - "refactor:" git: author: name: "Version Bot" email: "[email protected]"

2. Integration with CI/CD

@Component @Slf4j public class CiCdVersionIntegration { private final VersionManagementService versionService; public CiCdVersionIntegration(VersionManagementService versionService) { this.versionService = versionService; } @EventListener public void onBuildSuccess(BuildSuccessEvent event) { if (shouldBumpVersion(event)) { try { VersionBumpRequest request = createBumpRequest(event); VersionBumpResult result = versionService.bumpVersion(request); if (result.isSuccess()) { log.info("Automatically bumped version to: {}", result.getNewVersion()); // Trigger deployment or next pipeline stage } } catch (Exception e) { log.error("Automatic version bump failed: {}", e.getMessage()); } } } private boolean shouldBumpVersion(BuildSuccessEvent event) { return event.getBranch().equals("main") || event.getBranch().equals("master") || event.getBranch().startsWith("release/"); } private VersionBumpRequest createBumpRequest(BuildSuccessEvent event) { return VersionBumpRequest.builder() .projectName(event.getProjectName()) .currentVersion(event.getCurrentVersion()) .strategy(VersionManagementService.VersionIncrementStrategy.AUTO) .commitMessages(event.getCommits()) .createTag(true) .pushChanges(true) .build(); } }

Conclusion

Implementing Semantic Versioning in Java provides:

• Standardized versioning across all projects
• Automated version bumps based on commit messages
• Integration with build tools (Maven, Gradle)
• Git integration with automatic tagging
• REST APIs for version management
• Comprehensive validation and comparison

Key benefits include:

1. Clear communication of change impact through version numbers
2. Automated release process reducing human error
3. Integration with CI/CD pipelines
4. Historical tracking of version changes
5. Support for pre-releases and build metadata

This implementation can be extended with additional features like:

• Integration with artifact repositories (Nexus, Artifactory)
• Support for multi-module projects
• Advanced version range resolution for dependencies
• Integration with issue tracking systems (Jira, GitHub Issues)
• Automated changelog generation