semver-gradle-plugin

Gradle plugin for Updates the project version. A plugin that can updating the semantic versions like yarn version command.

Prerequisites:

• Java 8 or higher
• Gradle 6.x or higher

Installation

You need to add the following lines to your build.gradle file:

plugins {
    id 'com.github.rising3.semver' version '<latest version from the Gradle plugin portal>'
}

More...

New features

• Add supported for dry-run. More...
• Add supported for an automating generate a changelog with the ConventionalCommits. More...
• Add supported for an automating versioning with the ConventionalCommits. More...
• Add supported for a get current version from the latest tag. More...

Updating versions

Using the semver gradle plugin you can update the version of your package via the gradle task.

For example,starting with this gradle.properties file:

version=1.0.1

When we run the semver task:

gradle semver

question New version.

info Current version: 1.0.1
question New version: 1.0.2

> Task :semver

...

info New version: 1.0.2

We will get this updated gradle.properties file:

version=1.0.2

Note: The new version you enter must be a valid SemVer version.

Plugin Tasks

A plugin consists of the following tasks.

Latest

gradle semverLatest

Resolve a current version from the latest FILE, or TAG.

DependsOn: jar

Semver

gradle semver

A plugin that can updating the semantic versions like yarn version command. Other than that, it now supports conventional commits, so you can automate your releases.

DependsOn: check, semverLatest

Task options

gradle semver

Create a new version using an interactive session to prompt you for a new version.

gradle semver --new-version <version>

Creates a new version specified by <version>.

gradle semver --major
gradle semver --minor
gradle semver --patch

Creates a new version by incrementing the major, minor, or patch number of the current version.

gradle semver --premajor
gradle semver --preminor
gradle semver --prepatch

Creates a new prerelease version by incrementing the major, minor, or patch number of the current version and adding a prerelease number.

gradle semver --prerelease

Increments the prerelease version number keeping the main version.

gradle semver [--premajor | --preminor | --prepatch |--prerelease ] --preid <pre-identifier>

Adds an identifier specified by to be used to prefix premajor, preminor, prepatch or prerelease version increments.

gradle semver --conventional-commits

Create a new version according to the Conventional Commits rules. It refers to the commit log since the last release and creates a new version based on the following rules.

The commit message should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• fix: a commit the type fix patches a bug in your codebase (this correlates with --patch option).
• feat: a commit the type feat introduces a new feature to the codebase (this correlates with --minor option).
• BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with --major option). A BREAKING CHANGE can be part of commits of any type.
• Types other than fix and feat are allowed, but an automating versioning is not supported.

For more information, please refer to ConventionalCommits

gradle semver --conventional-commits --dryrun

Dry run the options. In a dry run, the following operations will be disabled.

• local/remote Git operations (git add, git commit, git tag, git push)
• GitHub release operations

Plugin Extension

The plugin defines an extension with the namespace semver. The following properties can be configured:

FILE:

1. Get current version from file. (gradle.properties, package.json, etc.)
2. Update to new version, save to file.
3. Create a git commit of save file.
4. Create a git tag of new version.

TAG:

1. Get latest tag for git.
2. Analyze tag, convert to semantic version.(current version)
3. Update to new version, save to file.
4. Create a git tag of new version.
5. Push tag to remote.

Example

For example, add with this build.gradle file:

semver {
    target = 'file'
    versionTagPrefix = 'v'
    versionGitMessage = 'v%s'
    noGitInit = false
    noGitCommand = false
    noGitTagVersion = false
    noGitPush = false
    noGitPushTag = false
    noPackageJson = true
}

Authentication

Push access to the remote repository

semver-gradle-plugin requires push access to the project Git repository in order to create git branch or git tag.

The Git authentication can be set with one of the following environment variables:

or the following system properties:

Here is an example of what a gradle.properties file:

~/.gradle/gradle.properties

systemProp.gh.actor=xxx
systemProp.gh.token=xxx

Changelog

A new version of the changelog can be generated automatically. The changelog will be generated from the Git commit log of the previous release or later.

It also supports the following:

• Markdown format
• ConventionalCommits
• GitHub Releases

For example, add with this build.gradle file:

semver {
    changeLog = 'FILE'
}

• NONE: Do nothing (default)
• FILE: Write the changelog to a file (CHANGELOG.md)
• GITHUB: Upload the changelog to GitHub Releases
• BOTH: Both FILE and GITHUB

Change the type order

For example, add with this build.gradle file:

semver {
    changeLogOrder = [
            '__breaking_change__',
            'feat',
            'fix',
    ]
}

Change the type title

For example, add with this build.gradle file:

semver {
    changeLogTitle = [
            build              : 'Build Improvements',
            chore              : 'Chores',
            ci                 : 'CI Improvements',
            docs               : 'Documentation',
            feat               : 'New Features',
            fix                : 'Bug Fixes',
            perf               : 'Performance Improvements',
            refactor           : 'Code Refactoring',
            style              : 'Styles',
            test               : 'Tests',
            __breaking_change__: '!!! BREAKING CHANGES !!!',
            __undefined__      : 'Other Changes',
    ]
}

Git tags

if you run semver task within a Git repository an annotated Git tag will be created by default following the format v0.0.0.

You can customize the git tag that is created or disable this behavior by using semver extension.

For example, add with this build.gradle file:

semver {
    // To change the prefix of the git tag you can use versionTagPrefix:
    versionTagPrefix = 'v'

    // Or you can change the git message using versionGitMessage where %s is the version string:
    versionGitMessage = 'v%s'

    // You can even enable or disable the git tagging behavior entirely by using noGitTagVersion:
    noGitTagVersion = false

    // You can even enable or disable the git command behavior entirely by using noGitCommand:
    noGitCommand = false
}

Supported for package.json

Version lifecycle methods

The semver task runs based on Gradle build lifecycle.

You can use the following mechanism of Gradle to execute another task before and after executing the semver task.

• dependsOn
• reconfigure

Executing the semver task overrides project.version, e.g. project.version will in the doFirst() hold the version before the version change, and in the doLast() it will hold the version after the version change.

Here is an example of what a build.gradle file:

tasks.semver.dependsOn test

tasks.semver.configure {
    doFirst {
        println "doFirst preversion: $project.version"
    }
    doLast {
        println "doLast postversion: $project.version"
    }
}

Executed semver task would look something like this:

info Current version: 0.1.1
question New version:  (default: 0.1.1): 0.1.2


> Task :semver
doFirst preversion: 0.1.1
info New version: 0.1.2
doLast postversion: 0.1.2

Building from source

You don’t need to build from source to use semver-gradle-plugin, but if you want to try out the latest, semver-gradle-plugin can be built and published to your local Maven cache using the Gradle wrapper.

You also need following to:

• Java 11 or higher
• Gradle 7.x or higher

$ ./gradlew publishToMavenLocal

If you want to build everything, use the build task:

$ ./gradlew build

License

The semver gradle plugin is released under version 2.0 of the Apache License.