semantic-version-maven-plugin

A Maven plugin for automated semantic versioning with markdown-based changelog management.

Table of Contents

• Overview
• Requirements
• Installation
• Goals
  • create
  • update
• Configuration Properties
• Examples
• License

Overview

The Semantic Version Maven Plugin automates version management using semantic versioning principles (MAJOR.MINOR.PATCH). It integrates changelog management through markdown files, enabling you to:

• Create version bump specifications with markdown changelog entries
• Automatically update POM file versions based on semantic versioning rules
• Maintain synchronized changelog files across single and multi-module Maven projects
• Support multiple versioning strategies for different project structures

Requirements

• Java: 17 or higher
• Maven: 3.9.12 or higher

Installation

Add the plugin to your pom.xml:

<build>
    <plugins>
        <plugin>
            <groupId>io.github.bsels</groupId>
            <artifactId>semantic-version-maven-plugin</artifactId>
            <version>1.0.0</version>
        </plugin>
    </plugins>
</build>

Goals

create

Full name: io.github.bsels:semantic-version-maven-plugin:create

Description: Creates a version markdown file that specifies which projects should receive which type of semantic version bump (PATCH, MINOR, or MAJOR). The goal provides an interactive interface to select projects and their version bump types, and allows you to write changelog entries either inline or via an external editor.

Phase: Not bound to any lifecycle phase (standalone goal)

Configuration Properties

Property	Type	Default	Description
versioning.modus	Modus	PROJECT_VERSION	Versioning strategy: • PROJECT_VERSION: All projects in multi-module builds • REVISION_PROPERTY: Only current project using the revision property • PROJECT_VERSION_ONLY_LEAFS: Only leaf projects (no modules)
versioning.directory	Path	.versioning	Directory for storing version markdown files
versioning.dryRun	boolean	false	Preview changes without writing files
versioning.backup	boolean	false	Create backup of files before modification

Example Usage

Basic usage (interactive mode):

mvn io.github.bsels:semantic-version-maven-plugin:create

With custom versioning directory:

mvn io.github.bsels:semantic-version-maven-plugin:create \
  -Dversioning.directory=.versions

Dry-run to preview:

mvn io.github.bsels:semantic-version-maven-plugin:create \
  -Dversioning.dryRun=true

Multi-module project (leaf projects only):

mvn io.github.bsels:semantic-version-maven-plugin:create \
  -Dversioning.modus=PROJECT_VERSION_ONLY_LEAFS

---

update

Full name: io.github.bsels:semantic-version-maven-plugin:update

Description: Updates POM file versions and CHANGELOG.md files based on version markdown files created by the create goal. The goal reads version bump specifications from markdown files, applies semantic versioning to project versions, updates dependencies in multi-module projects, and merges changelog entries into CHANGELOG.md files.

Phase: Not bound to any lifecycle phase (standalone goal)

Configuration Properties

Property	Type	Default	Description
versioning.bump	VersionBump	FILE_BASED	Version bump strategy: • FILE_BASED: Use version markdown files from .versioning directory • MAJOR: Apply MAJOR version bump to all projects • MINOR: Apply MINOR version bump to all projects • PATCH: Apply PATCH version bump to all projects
versioning.modus	Modus	PROJECT_VERSION	Versioning strategy: • PROJECT_VERSION: All projects in multi-module builds • REVISION_PROPERTY: Only current project using the revision property • PROJECT_VERSION_ONLY_LEAFS: Only leaf projects (no modules)
versioning.directory	Path	.versioning	Directory containing version markdown files
versioning.dryRun	boolean	false	Preview changes without writing files
versioning.backup	boolean	false	Create backup of POM and CHANGELOG files before modification

Example Usage

Basic usage (file-based versioning):

mvn io.github.bsels:semantic-version-maven-plugin:update

Force MAJOR version bump (override version files):

mvn io.github.bsels:semantic-version-maven-plugin:update \
  -Dversioning.bump=MAJOR

Force MINOR version bump:

mvn io.github.bsels:semantic-version-maven-plugin:update \
  -Dversioning.bump=MINOR

Force PATCH version bump:

mvn io.github.bsels:semantic-version-maven-plugin:update \
  -Dversioning.bump=PATCH

Dry-run to preview changes:

mvn io.github.bsels:semantic-version-maven-plugin:update \
  -Dversioning.dryRun=true

With backup files:

mvn io.github.bsels:semantic-version-maven-plugin:update \
  -Dversioning.backup=true

Custom versioning directory:

mvn io.github.bsels:semantic-version-maven-plugin:update \
  -Dversioning.directory=.versions

Multi-module project with revision property:

mvn io.github.bsels:semantic-version-maven-plugin:update \
  -Dversioning.modus=REVISION_PROPERTY

Configuration Properties

Common Properties

These properties apply to both create and update goals:

Property	Type	Default	Description
versioning.modus	Modus	PROJECT_VERSION	Defines versioning strategy for project structure: • PROJECT_VERSION: Process all projects in topological order • REVISION_PROPERTY: Process only the current project using the revision property • PROJECT_VERSION_ONLY_LEAFS: Process only leaf projects (no child modules)
versioning.directory	Path	.versioning	Directory path for version markdown files (absolute or relative to project root)
versioning.dryRun	boolean	false	When true, performs all operations without writing files (logs output instead)
versioning.backup	boolean	false	When true, creates .bak backup files before modifying POM and CHANGELOG files

update-Specific Properties

Property	Type	Default	Description
versioning.bump	VersionBump	FILE_BASED	Determines version increment strategy: • FILE_BASED: Read version bumps from markdown files in .versioning directory • MAJOR: Force MAJOR version increment (X.0.0) for all projects • MINOR: Force MINOR version increment (0.X.0) for all projects • PATCH: Force PATCH version increment (0.0.X) for all projects

Examples

Example 1: Single Project Workflow

1. Create version specification:

   mvn io.github.bsels:semantic-version-maven-plugin:create

   • Select MINOR version bump
   • Enter changelog: "Added new user authentication feature"

2. Preview changes:

   mvn io.github.bsels:semantic-version-maven-plugin:update -Dversioning.dryRun=true

3. Apply version update:

   mvn io.github.bsels:semantic-version-maven-plugin:update

Example 2: Multi-Module Project Workflow

1. Create version specifications for multiple modules:

   mvn io.github.bsels:semantic-version-maven-plugin:create

   • Select module-api → MAJOR (breaking changes)
   • Select module-core → MINOR (new features)
   • Enter changelog for each module

2. Update with backups:

   mvn io.github.bsels:semantic-version-maven-plugin:update -Dversioning.backup=true

Example 3: Emergency Patch Release

Skip version file creation and force PATCH bump:

mvn io.github.bsels:semantic-version-maven-plugin:update -Dversioning.bump=PATCH

Example 4: POM Configuration

Configure the plugin directly in pom.xml:

<build>
    <plugins>
        <plugin>
            <groupId>io.github.bsels</groupId>
            <artifactId>semantic-version-maven-plugin</artifactId>
            <version>1.0.0</version>
            <configuration>
                <modus>PROJECT_VERSION</modus>
                <versionDirectory>.versioning</versionDirectory>
                <dryRun>false</dryRun>
                <backupFiles>true</backupFiles>
                <versionBump>FILE_BASED</versionBump>
            </configuration>
        </plugin>
    </plugins>
</build>

License

This project is licensed under the MIT License. See the LICENSE file for details.