semantic-version-maven-plugin

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

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.2.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.identifier`	`ArtifactIdentifier`	`GROUP_ID_AND_ARTIFACT_ID`	Artifact key format in version Markdown files: • `GROUP_ID_AND_ARTIFACT_ID`: use `groupId:artifactId` keys (default) • `ONLY_ARTIFACT_ID`: use artifactId only when all modules share the same groupId
`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
`versioning.commit.message.create`	`String`	`Created version Markdown file for {numberOfProjects} project(s)`	Commit message template for version Markdown file creation. Use `{numberOfProjects}` placeholder for project count
`versioning.git`	`Git`	`NO_GIT`	Defines the git operation mode: • `NO_GIT`: no git operations will be performed • `STASH`: added changed files to the git stash • `COMMIT`: commit all changed files with the configured commit message

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.identifier`	`ArtifactIdentifier`	`GROUP_ID_AND_ARTIFACT_ID`	Artifact key format in version Markdown files: • `GROUP_ID_AND_ARTIFACT_ID`: use `groupId:artifactId` keys (default) • `ONLY_ARTIFACT_ID`: use artifactId only when all modules share the same groupId
`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
`versioning.commit.message.update`	`String`	`Updated {numberOfProjects} project version(s) [skip ci]`	Commit message template for version updates. Use `{numberOfProjects}` placeholder for project count
`versioning.dependency.bump.message`	`String`	`Project version bumped as result of dependency bumps`	Changelog entry text used when a project version is bumped because of dependency updates
`versioning.update.scripts`	`String`	`-`	Script paths to execute per updated module, separated by the OS path separator. Each script runs in the module directory with `CURRENT_VERSION`, `NEW_VERSION`, `DRY_RUN` (`true` or `false`), `GIT_STASH` (`true` or `false`), `EXECUTION_DATE` (YYYY-MM-DD) environment variables.
`versioning.version.header`	`String`	`{version} - {date#YYYY-MM-DD}`	Header format for version Markdown files. Supports `{version}` and `{date#YYYY-MM-DD}` placeholders; date uses a `DateTimeFormatter` pattern.
`versioning.changelog.header`	`String`	`Changelog`	Header label for the changelog title (H1)
`versioning.major.header`	`String`	`Major`	Header label for major changes in the changelog
`versioning.minor.header`	`String`	`Minor`	Header label for minor changes in the changelog
`versioning.patch.header`	`String`	`Patch`	Header label for patch changes in the changelog
`versioning.other.header`	`String`	`Other`	Header label for non-semantic changes in the changelog
`versioning.git`	`Git`	`NO_GIT`	Defines the git operation mode: • `NO_GIT`: no git operations will be performed • `STASH`: added changed files to the git stash • `COMMIT`: commit all changed files with the configured commit message

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

Custom version file header:

mvn io.github.bsels:semantic-version-maven-plugin:update \
  -Dversioning.version.header='Release {version} ({date#YYYY-MM-DD})'

Multi-module project with revision property:

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

verify

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

Description: Verifies that version Markdown files are consistent with the project scope. The goal reads version Markdown files, validates that all referenced artifacts exist in scope, enforces the selected verification mode, and optionally requires consistent version bumps across all projects. When versioning.git is not NO_GIT, it runs git status before verification. This goal does not write files; versioning.dryRun and versioning.backup have no effect.

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

Configuration Properties

Property	Type	Default	Description
`versioning.verification.mode`	`VerificationMode`	`ALL_PROJECTS`	Verification scope: • `NONE`: skip verification • `AT_LEAST_ONE_PROJECT`: require at least one version-marked project • `DEPENDENT_PROJECTS`: require all dependent projects to be version-marked • `ALL_PROJECTS`: all projects in scope must be version-marked
`versioning.verification.consistent`	`boolean`	`false`	When `true`, all version-marked projects must share the same version bump type
`versioning.modus`	`Modus`	`PROJECT_VERSION`	Project scope for verification: • `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.identifier`	`ArtifactIdentifier`	`GROUP_ID_AND_ARTIFACT_ID`	Artifact key format in version Markdown files: • `GROUP_ID_AND_ARTIFACT_ID`: use `groupId:artifactId` keys (default) • `ONLY_ARTIFACT_ID`: use artifactId only when all modules share the same groupId
`versioning.directory`	`Path`	`.versioning`	Directory containing version Markdown files
`versioning.git`	`Git`	`NO_GIT`	Git mode. Any value other than `NO_GIT` triggers a `git status` check before verification. Supported modes: • `NO_GIT`: no git operations will be performed • `STASH`: added changed files to the git stash • `COMMIT`: commit all changed files with the configured commit message

Example Usage

Basic verification:

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

Verify dependent projects and require consistent bumps:

mvn io.github.bsels:semantic-version-maven-plugin:verify \
  -Dversioning.verification.mode=DEPENDENT_PROJECTS \
  -Dversioning.verification.consistent=true

Configuration Properties

Common Properties

These properties apply to create, update, and verify goals. The verify goal does not use versioning.dryRun or versioning.backup:

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.identifier`	`ArtifactIdentifier`	`GROUP_ID_AND_ARTIFACT_ID`	Artifact key format in version Markdown files: • `GROUP_ID_AND_ARTIFACT_ID`: use `groupId:artifactId` keys (default) • `ONLY_ARTIFACT_ID`: use artifactId only when all modules share the same groupId
`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
`versioning.git`	`Git`	`NO_GIT`	Defines the git operation mode: • `NO_GIT`: no git operations will be performed • `STASH`: added changed files to the git stash • `COMMIT`: commit all changed files with the configured commit message

create-Specific Properties

Property	Type	Default	Description
`versioning.commit.message.create`	`String`	`Created version Markdown file for {numberOfProjects} project(s)`	Commit message template used when creating version Markdown files. The `{numberOfProjects}` placeholder is replaced with the actual count

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
`versioning.commit.message.update`	`String`	`Updated {numberOfProjects} project version(s) [skip ci]`	Commit message template used when updating project versions. The `{numberOfProjects}` placeholder is replaced with the actual count
`versioning.dependency.bump.message`	`String`	`Project version bumped as result of dependency bumps`	Changelog entry text used when a project version is bumped because of dependency updates
`versioning.update.scripts`	`String`	`-`	Script paths to execute per updated module, separated by the OS path separator. Each script runs in the module directory with `CURRENT_VERSION`, `NEW_VERSION`, `DRY_RUN` (`true` or `false`), `GIT_STASH` (`true` or `false`), `EXECUTION_DATE` (YYYY-MM-DD) environment variables.
`versioning.version.header`	`String`	`{version} - {date#YYYY-MM-DD}`	Header format for version Markdown files. Supports `{version}` and `{date#YYYY-MM-DD}` placeholders; date uses a `DateTimeFormatter` pattern.
`versioning.changelog.header`	`String`	`Changelog`	Header label for the changelog title (H1)
`versioning.major.header`	`String`	`Major`	Header label for major changes in the changelog
`versioning.minor.header`	`String`	`Minor`	Header label for minor changes in the changelog
`versioning.patch.header`	`String`	`Patch`	Header label for patch changes in the changelog
`versioning.other.header`	`String`	`Other`	Header label for non-semantic changes in the changelog

verify-Specific Properties

Property	Type	Default	Description
`versioning.verification.mode`	`VerificationMode`	`ALL_PROJECTS`	Verification scope: • `NONE`: skip verification • `AT_LEAST_ONE_PROJECT`: require at least one version-marked project • `DEPENDENT_PROJECTS`: require all dependent projects to be version-marked • `ALL_PROJECTS`: all projects in scope must be version-marked
`versioning.verification.consistent`	`boolean`	`false`	When `true`, all version-marked projects must share the same version bump type

Examples

Example 1: Single Project Workflow

Create version specification:
```
mvn io.github.bsels:semantic-version-maven-plugin:create
```
- Select MINOR version bump
- Enter changelog: "Added new user authentication feature"

Preview changes:

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

Apply version update:

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

Example 2: Multi-Module Project Workflow

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github		.github
.mvn/wrapper		.mvn/wrapper
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml
update-readme.sh		update-readme.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

semantic-version-maven-plugin

Table of Contents

Overview

Requirements

Installation

Goals

create

Configuration Properties

Example Usage

update

Configuration Properties

Example Usage

verify

Configuration Properties

Example Usage

Configuration Properties

Common Properties

create-Specific Properties

update-Specific Properties

verify-Specific Properties

Examples

Example 1: Single Project Workflow

Example 2: Multi-Module Project Workflow

Example 3: Emergency Patch Release

Example 4: POM Configuration

License

About

Uh oh!

Releases 3

Contributors 2

Uh oh!

Languages

License

bsels/semantic-version-maven-plugin

Folders and files

Latest commit

History

Repository files navigation

semantic-version-maven-plugin

Table of Contents

Overview

Requirements

Installation

Goals

create

Configuration Properties

Example Usage

update

Configuration Properties

Example Usage

verify

Configuration Properties

Example Usage

Configuration Properties

Common Properties

create-Specific Properties

update-Specific Properties

verify-Specific Properties

Examples

Example 1: Single Project Workflow

Example 2: Multi-Module Project Workflow

Example 3: Emergency Patch Release

Example 4: POM Configuration

License

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 3

Contributors 2

Uh oh!

Languages