Skip to content

This plugin provides project configuration and tasks for version handling based on the used SCM of the project.

License

Notifications You must be signed in to change notification settings

ISSupport/scmversion-gradle-plugin

 
 

Repository files navigation

SCM Version Plugin

Note
Version 3.4 (and later) of this plugin will only work with JDK 8, Gradle 4.4 and later. Version 3.3 can be used for Gradle 4.4 and previous version of Gradle 4.

Summary

Based on the used SCM (Source Control Management) this plugin provides project configuration handling and specific tasks regarding the version handling of the project. The information of the used SCM is identified by special directories in the project directory ('.git', '.svn'). The plugin supports the following SCMs:

  • git

  • svn

  • file (limited functionality)

Branches and tags are used for the calculation of the project version. The basic functionality for Git and Subversion is the same.

Note
A file-based project does not support the calculation of the version based on previous versions.

It is also possible to identify the changes between the current working copy and the previous version. This functionality can also be used on a CI server during the creation of a new tag. In this case the changes between two versions are written to a file.

Version Information from the SCM

This plugin adds the possibility to calculate version information of a project from the used SCM structure. It initializes a project property useSCMVersionConfig. The value of this property is true, if the plugin was applied and can be used by the own build logic and other plugins.

Subversion

This implementation depends on SVNKit 1.8. Therefore an installed SVN client 1.8 for the access to the stored Subversion credentials is required. For a correct calculation of the version, the access to the SVN repository must be available.

Caution
  1. This plugin assumes the standard Subversion structure:

    <project>
     |
     +- <code structure of the trunk>
     |
     +- branches
     |  |
     |  +- <branch name>
     |      |
     |      +- <code structure of the branch>
     |
     +- tags
        |
        +- <tag name>
            |
            +- <code structure of the tag>
  2. SVN version calculation is not working without network access.

Configuration Without Remote Access

Configuration with a Project Property

If there is no access to a remote repository, it is possible to specify a version string as project property offlineVersion (see above)

gradlew -PofflineVersion=9.9.0.0-LOCAL publish

This will add the version '9.9.0.0-LOCAL' to your project. It is possible to add this property also to the gradle.properties file in the Gradle user home. In this case all projects with this applied plugin uses the same version.

Configuration with a Static Version

This configuration is also working without any remote access, but project specific, because the replacement for the version information is stored in the build directory of the project. If <project build dir>/scmversion/static.version exists and the content is not empty, the content of this is used for the version.

If the first call of a project task is started with a parameter staticVersion and a version information, the file will be created with the version information.

gradlew -PstaticVersion=TRUNKVER publish

This will set the version to TRUNKVER. The project runs now always with this version. It is possible to remove this configuration with an empty string for staticVersion or if exists with the task clean.

gradlew -PstaticVersion= publish

This command will reset the version to the standard behaviour.

Caution
This version will be published to the specified repository and can be used by other processes!

Git

The version can be calculated from the local clone without access to the remote repository. The plugin assumes, that the default branch is called 'master'.

Version Calculation

The plugin detects tags and branches with version information on special prefixes. These prefixes are configured based on the configuration 'prefixes'. For parsing, calculation and sorting a library for an extended version object is used. The library supports version numbers with three or four decimal numbers. Furthermore a special pattern is supported.

<prefix>_<version>[-<featurebranch name>][-<build extension>]

Therefore branch names must comply with the following patterns. All examples use the default configuration. Depending on a special environment configuration (RUNONCI) the build extension is empty or SNAPSHOT, if this setting is true, otherwise it is LOCAL. If no prefix is specified the plugin assumes that the branch is a feature branch. If the version is not part of the branch name, the version is taken from the last tag.

Feature Branches, Hotfix Branches and Bugfix Branches

<feature, hotfix or bugfix branch prefix>_<version>-<branch name>

These are the default values

Branch Type Default value

Feature Branch

'FB'

Hotfix Branch

'HB'

Bugfix Branch

'BB'

The version is the original version of the master/trunk.

Example
FB_1.0.0-JIRA-4711
FB_1.0.0-FeatureBranchName

Stabilization branch

<stabilization branch prefix>_<version>

The default stabilization branch prefix is 'SB'. The version is the base version for this branch. In most cases, it is the major version of the master/trunk, before the branch was created.

Example
SB_1        Stabilization branch for version 1.0.0 to 1.X.X
SB_1.0      Stabilization branch for version 1.0.0 to 1.0.X

Release Tag

<release prefix>_<version>[-<featurebranch name>][-<build extension>]

The default release prefix is 'RELEASE'. The version is the base version of the branch. In the most cases, it is the major version of the master/trunk, before the branch was created.

Example
RELEASE_1.1.0                   Release tag for version 1.1.0
RELEASE_1.1.0-dev.1             Tag of a development milestone release for version 1.1.0
RELEASE_1.1.0-rc.1              Tag of a release candidate for version 1.1.0
RELEASE_1.0.0-JIRA-4711-dev.1   Tag of a development milestone release of a feature branch version 1.0.0-JIRA-4711

Version Calculation on Git

  • Default Branch (master)
    The plugin is looking for a tag on the branch. If there is no tag the default value is used and extended with SNAPSHOT.

  • Branch / Feature,Hotfix,Bugfix Branch
    The plugin is looking for a tag on the branch. If there is no valid tag on the branch, the version is taken from the name of the branch. The version will be always extended with SNAPSHOT on the CI server.

  • Tags
    Without local changes the plugin tries to calculate the name from the tag name.

Version Calculation on Subversion

  • Trunk
    The plugin is looking for a tag that matches the specified criteria. In the most cases, the version is calculated from branches and will be extended with SNAPSHOT. This behavior can be configured.

  • Branch / Feature,Hotfix,Bugfix Branch
    The plugin is looking for a tag that matches the branch name. If there is no valid tag on the branch, the version is taken from the name of the branch. The version will be always extended with SNAPSHOT on the CI server.

  • Tags
    Without local changes the plugin tries to calculate the name from the tag name.

Usage

To use the Gradle SCM Version plugin provided by Intershop, include the following in your build script of your root project:

build.gradle
plugins {
    id 'com.intershop.gradle.scmversion' version '4.0.0'
}

scm {
    prefixes {
        //default is 'SB'
        stabilizationPrefix = 'SBP'

        //default is 'FB'
        featurePrefix = 'FBP'

        //default is 'HB'
        hotfixPrefix = 'HBP'

        //default is 'BB'
        bugfixPrefix = 'BBP'

        //default is Release
        tagPrefix = 'RBP'
    }

    version {
        type = 'threeDigits'
        initialVersion = '1.0.0'
    }

    changelog {
        targetVersion = '1.0.0'
        changelogFile = new File(project.buildDir, 'changelog/changelogset.asciidoc')
        filterProject = true
    }
}

version = scm.version.version

Tasks

The Intershop SCM Version plugin adds the following tasks to the project:

Task name Type Description

showVersion

ShowVersion

This task shows the current version of the working copy.

tag

CreateTag

This task creates a tag based on the current working copy.
It makes changes to the SCM.

branch

CreateBranch

This task creates a branch based on the current working copy.
It makes changes to the SCM.
For creating a feature branch it is necessary to specify a short name for the feature in a project property feature.

toVersion

ToVersion

This task moves the working copy to a target version. This version must be specified in a project property targetVersion. It is also possible to specify the short name of a feature in a property feature and the kind of branch in the property branchType, that should be used. The default value for the type is branch. Possible values are featureBranch, hotfixBranch, bugfixBranch, tag. It changes the working copy.

release

PrepareRelease

This task creates a tag, if necessary, and move the the working copy to the version.
It changes the working copy.

changelog

CreateChangeLog

This task creates a change log with all changes between the latest commit of the current working copy and the tag of the previous version. It is possible to specify another 'previous' version.
The tag for this version is mandatory.

All task are part of the package 'com.intershop.gradle.scm.task'

Project Extension 'scm'

This plugin adds an extension scm to the root project. This extension contains all plugin configurations.

Methods

Method Values Description

prefixes(configure)

PrefixConfig

This is the extension object for the configuration of branch prefixes.

user(configure)

ScmUser

This extension is used for the SCM user authentication.
This extension can be configured over environment variables and project properties.

key(configure)

ScmKey

This is also used for the SCM user authentication.
This extension can be configured over environment variables and project properties.

version(configure)

ScmVersion

This extension contains settings for version calculation and reads properties for the current version and previous version.

changelog(configure)

ScmChangelog

This extension contains settings for change log configuration.

Prefix configuration 'prefixes' (PrefixConfig)

Property Type Default value Description

stabilizationPrefix

String

SB

Prefix for stabilization branches

featurePrefix

String

FB

Prefix for feature branches

hotfixPrefix

String

HB

Prefix for hotfix branches

bugfixPrefix

String

BB

Prefix for bugfix branches

tagPrefix

String

RELEASE

Prefix for release tags

prefixSeperator

String

_

Separator between prefix and version

Authentication

User object 'user' (ScmUser)
Property Type Default value Description

name

String

''

Username or token
This can be overwritten by the system or environment variable SCM_USERNAME or project property scmUserName.

password

String

''

Password
This can be overwritten by the system or environment variable SCM_PASSWORD or project property scmUserPasswd.

SSH Key object 'key' (ScmKey) (only for Git)
Property Type Default value Description

file

File

null

Private key for SCM authentication
This can be overwritten by the system or environment variable SCM_KEYFILE or project property scmKeyFile. The plugin uses per default for ssh access <user_home>/.ssh/id_rsa or <user_home>/.ssh/id_dsa without passphrase.

passphrase

String

''

passphrase for private key
This can be overwritten by the system or environment variable SCM_KEYPASSPHRASE or project property scmKeyPassphrase.

Version object 'version' (ScmVersion)

Property Type Default value Values Description

type

String

threeDigits

fourDigits
threeDigits

The number of used decimal numbers for a version number.

dryRun

boolean

false

false
true

Tasks will run without changes on the working copy or SCM.
This can be overwritten by the system or environment variable DRYRUN or project property dryRun.

runOnCI

boolean

false

false
true

This configuration must be true, if the project is used on a CI server.
This can be overwritten by the system or environment variable RUNONCI or project property runOnCI.

increment

String

null

MAJOR
MINOR
PATCH
HOTFIX

If this property is set, the configured position is used for incrementing the version.
This can be overwritten by the system or environment variable INCREMENT, or project property increment.

initialVersion

String

'1.0.0.0'
'1.0.0'

The inital version if a calculation from SCM is not possible.

branchType

String

tag

branch
tag

The branch which is primarily used for the version calculation.

patternDigits

int

2

1
2
3 (available only if ScmVersion type is fourDigits)

Determines the number of digit blocks of the version number that will be used for calculating the version filter from branches.

defaultMetadata

String

''

This is used for releases of feature branches.

useBuildExtension

boolean

false

false
true

Build extension will be removed for SNAPSHOT extensions if this property is false.

majorVersionOnly

boolean

true

This property affects only GIT based repositories.
If this property is true, the version is always only the major version. If the increment property is always configure for MAJOR the version will be increased.

disableSCM

boolean

false

false
true

If this property is true, the initial version is always used and the SCM usage is disabled. The environment variable 'SCMVERSIONEXT' or the project variable 'scmVersionExt' will be used on the CI server for special extensions.
If set to:
'SNAPSHOT' - 'SNAPSHOT' will be added to the version.
'RELEASE' - intial version is used without any extension.
If no value is specified a time stamp will be added.
On a local developer machine 'LOCAL' will be added to the version.

version

String

initialVersion

read only

Returns the version of the working copy

branchName

String

''

read only

Returns the branch name only (String after last /)

versionExt

String

''

read only

see description for disableSCM. The environment variable SCMVERSIONEXT or the project variable scmVersionExt is used for the return value.

previousVersion

String

''

read only

Returns the previous version of the working copy.

previousVersionTag

VersionTag

null

read only

Returns an object with the previous version and the associated release tag.

continuousRelease

boolean

false

-

If this value is true and the publishing runs on a CI server the revision id or the hash string with the prefix "rev.id." will attached to the version instead of SNAPSHOTS.

continuousReleaseBranches

List<String>

[]

-

continuousRelease is always used if the active branch is master or trunk. If continuous releases should be done from other branches, it is possible to extend the list of branches with this property.

Changelog Object 'changeLog' (ScmChangeLog)

Property Type Default value Description

previousVersion

String

version.previousVersion

Any version with tag for change log calculation.
It is possible to override the value with the enviroment variable PREV_VERSION

changelogFile

File

<buildDir>/changelog/
changelog.asciidoc

The change log will be written to this file. The log file is empty, if the previous version does not exists.

filterProject

boolean

false

Filter changed files for projects (first folder in changed files must be identical to last folder of project svn url)

Example Configurations

Simple Configuration

plugins {
    id 'com.intershop.gradle.scmversion' version '4.0.0'
}


scm {
    version {
        type = 'threeDigits'
        initialVersion = '1.0.0'
    }
}

version = scm.version.version

gradle.properties with Authentication Configuration

This configuration works for Subversion and Git (http(s)://…​). It is necessary to specify username and password for this kind of repositories.

scmUserName = username
scmUserPasswd = password

This configuration works for GitLab / GitHub (ssh://…​) with a private key and if necessary with a passphrase. There is no default value for the key.

# without passphrase
scmKeyFile = /user/home/.ssh/id_rsa
# with passphrase
scmKeyFile = /user/home/.ssh/id_rsa
scmKeyPassphrase = passphrase

To use ssh keys you have to switch your repository from https to ssh with the following command:

git remote set-url origin git@gitlab.coporate.com:yourname/yourrepo.git

Simple Configuration Without SCM

This configuration can be used when a different version control system is used in the project or another version schema is set in the project.

Note
Using this configuration a lot of the features are no longer available.
plugins {
    id 'com.intershop.gradle.scmversion' version '4.0.0'
}

scm {
    version {
        disableSCM = true
        initialVersion = '1.0.0'
    }
}

version = scm.version.version

On a CI server some properties must be transfered via the command line:

snapshot build:
./gradlew publish -PrunOnCI=true -PscmVersionExt=SNAPSHOT
release build:
./gradlew publish -PrunOnCI=true -PscmVersionExt=RELEASE
Note
After a release it is necessary to change the version manually.

Test

The integration tests use test repositories. Therefore, it is necessary to specify project properties for the test execution.

Table 1. Subversion test configuration
Test Property Description Value

svnurl

Root URL of the test project

Must be specified with environment variable SVNURL

svnuser

User name of Subversion test user

Must be specified with environment variable SVNUSER

svnpasswd

Password for Subversion test user

Must be specified with environment variable SVNPASSWD

Table 2. Git test configuration
Test Property Description Value

giturl

URL of the test project

Must be specified with environment variable GITURL

gituser

User name of Git test user

Must be specified with environment variable GITUSER

gitpasswd

Password for Git test user

Must be specified with environment variable GITPASSWD

License

Copyright 2014-2016 Intershop Communications.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

About

This plugin provides project configuration and tasks for version handling based on the used SCM of the project.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Groovy 99.8%
  • Shell 0.2%