https://github.com/bsels/semantic-version-maven-plugin
A Maven plugin that automates semantic versioning with markdown‑based changelog management. Provides two standalone goals: create generates interactive version spec files; update applies those specs, bumps project versions, and merges CHANGELOG entries.
https://github.com/bsels/semantic-version-maven-plugin
changelog changelog-generator java markdown maven maven-plugin maven-pom plugin semantic-versioning versioning versioning-plugin
Last synced: 2 months ago
JSON representation
A Maven plugin that automates semantic versioning with markdown‑based changelog management. Provides two standalone goals: create generates interactive version spec files; update applies those specs, bumps project versions, and merges CHANGELOG entries.
- Host: GitHub
- URL: https://github.com/bsels/semantic-version-maven-plugin
- Owner: bsels
- License: mit
- Created: 2026-01-03T14:33:47.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-03-21T15:03:35.000Z (3 months ago)
- Last Synced: 2026-03-22T05:34:51.212Z (3 months ago)
- Topics: changelog, changelog-generator, java, markdown, maven, maven-plugin, maven-pom, plugin, semantic-versioning, versioning, versioning-plugin
- Language: Java
- Homepage:
- Size: 174 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# semantic-version-maven-plugin
[](https://github.com/bsels/semantic-version-maven-plugin/releases)
[](https://search.maven.org/artifact/io.github.bsels/semantic-version-maven-plugin)
[](https://github.com/bsels/semantic-version-maven-plugin/actions/workflows/push-release.yaml)
[](https://github.com/bsels/semantic-version-maven-plugin/actions/workflows/release-build.yaml)
[](https://opensource.org/licenses/MIT)
. 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):
```bash
mvn io.github.bsels:semantic-version-maven-plugin:create
```
**With custom versioning directory**:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:create \
-Dversioning.directory=.versions
```
**Dry-run to preview**:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:create \
-Dversioning.dryRun=true
```
**Multi-module project (leaf projects only)**:
```bash
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):
```bash
mvn io.github.bsels:semantic-version-maven-plugin:update
```
**Force MAJOR version bump** (override version files):
```bash
mvn io.github.bsels:semantic-version-maven-plugin:update \
-Dversioning.bump=MAJOR
```
**Force MINOR version bump**:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:update \
-Dversioning.bump=MINOR
```
**Force PATCH version bump**:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:update \
-Dversioning.bump=PATCH
```
**Dry-run to preview changes**:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:update \
-Dversioning.dryRun=true
```
**With backup files**:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:update \
-Dversioning.backup=true
```
**Custom versioning directory**:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:update \
-Dversioning.directory=.versions
```
**Custom version file header**:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:update \
-Dversioning.version.header='Release {version} ({date#yyyy-MM-dd})'
```
**Multi-module project with revision property**:
```bash
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**:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:verify
```
**Verify dependent projects and require consistent bumps**:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:verify \
-Dversioning.verification.mode=DEPENDENT_PROJECTS \
-Dversioning.verification.consistent=true
```
---
### graph
**Full name**: `io.github.bsels:semantic-version-maven-plugin:graph`
**Description**: Generates a JSON representation of the dependency graph for Maven projects within the current execution
scope. It identifies internal dependencies between projects and can output the graph either to the console or to a
specified file. The output includes transitive dependencies sorted in build order (topological order).
**Phase**: Not bound to any lifecycle phase (standalone goal)
#### Configuration Properties
| Property | Type | Default | Description |
|----------------------------|---------------|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `versioning.graphOutput` | `GraphOutput` | `ARTIFACT_AND_FOLDER` | Specifies the graph output format:
• `ARTIFACT_ONLY`: Only Maven artifact identifiers
• `FOLDER_ONLY`: Only project folder paths
• `ARTIFACT_AND_FOLDER`: Both artifact identifiers and folder paths |
| `versioning.outputFile` | `Path` | `-` | Path to the output file. If not specified, the graph is printed to the console. |
| `versioning.relativePaths` | `boolean` | `true` | When `true`, project folder paths are resolved relative to the execution root; otherwise, absolute paths are used. |
| `versioning.modus` | `Modus` | `PROJECT_VERSION` | Project scope for the graph:
• `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) |
#### Output Format Description
The generated JSON is a map where each key is a project's artifact identifier (`groupId:artifactId`), and the value is a
list of its internal dependencies.
**ARTIFACT_ONLY**:
```json
{
"io.github.bsels:parent": [],
"io.github.bsels:child": [
"io.github.bsels:parent"
]
}
```
**FOLDER_ONLY**:
```json
{
"io.github.bsels:parent": [],
"io.github.bsels:child": [
"."
]
}
```
**ARTIFACT_AND_FOLDER**:
```json
{
"io.github.bsels:parent": [],
"io.github.bsels:child": [
{
"artifact": {
"groupId": "io.github.bsels",
"artifactId": "parent"
},
"folder": "."
}
]
}
```
#### Example Usage
**Basic usage** (print to console):
```bash
mvn io.github.bsels:semantic-version-maven-plugin:graph
```
**Write to file with absolute paths**:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:graph \
-Dversioning.outputFile=graph.json \
-Dversioning.relativePaths=false
```
**Artifact-only output**:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:graph \
-Dversioning.graphOutput=ARTIFACT_ONLY
```
## 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 |
### graph-Specific Properties
| Property | Type | Default | Description |
|----------------------------|---------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `versioning.graphOutput` | `GraphOutput` | `ARTIFACT_AND_FOLDER` | Specifies the graph output format:
• `ARTIFACT_ONLY`: Only artifact identifiers
• `FOLDER_ONLY`: Only folder paths
• `ARTIFACT_AND_FOLDER`: Artifacts and folder paths |
| `versioning.outputFile` | `Path` | `-` | Path to the output file. If not specified, output is printed to the console. |
| `versioning.relativePaths` | `boolean` | `true` | When `true`, project paths are relative to execution root; otherwise, absolute. |
## Examples
### Example 1: Single Project Workflow
1. **Create version specification**:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:create
```
- Select MINOR version bump
- Enter changelog: "Added new user authentication feature"
2. **Preview changes**:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:update -Dversioning.dryRun=true
```
3. **Apply version update**:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:update
```
### Example 2: Multi-Module Project Workflow
1. **Create version specifications for multiple modules**:
```bash
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**:
```bash
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:
```bash
mvn io.github.bsels:semantic-version-maven-plugin:update -Dversioning.bump=PATCH
```
### Example 4: POM Configuration
Configure the plugin directly in `pom.xml`:
```xml
io.github.bsels
semantic-version-maven-plugin
1.3.2
PROJECT_VERSION
.versioning
false
true
FILE_BASED
```
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.