2019-08-23

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

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.

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. 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> SVN version calculation is not working without network access.

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.

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. This version will be published to the specified repository and can be used by other processes!

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

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.

<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. FB_1.0.0-JIRA-4711 FB_1.0.0-FeatureBranchName

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

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. A checkout of a single commit (detached head) without a tag name will be specially treated. The last found version is used for the version string. This is extended by the short hash value and 'SNAPSHOT', e.g. 2.0.0-rev.id.ad73b69-SNAPSHOT. If the environment variable 'CONTINUOUSRELEASE' or the project variable 'continuousRelease' is set, the extension SNAPSHOT is not added.

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.

To use the Gradle SCM Version plugin provided by Intershop, include the following in your build script of your root project: plugins { id 'com.intershop.gradle.scmversion' version '2.7.2' } 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 { previousVersion = '1.0.0' changeLogFile = new File(project.buildDir, 'changelog/changelogset.asciidoc') filterProject = true } } version = scm.version.version

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. createChangelog 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'

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

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.

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

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.

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.

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. branchWithVersion boolean true This property affects only GIT based repositories. If this property is false the version of feature branches is calculated from any tag on the branch. Therefore it is not necessary to specify a version in the branch name. majorVersionOnly boolean true This property affects only GIT based repositories. If this property is true and branchWithVersion is false, 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 false true For continuous releases it is helpful to use an version extension with an relation to the source control. It is possible to enable this configuration also over the environment variable 'CONTINUOUSRELEASE' or the project variable 'continuousRelease'. continuousReleaseBranches List<String> [] Branchnames In combination with continuousRelease it should be possible to specify the branches for this kind of version extension. Continuous releases will be also used for the master or trunk. If you want extend the list of branches, it is possible to extend the list.

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)

plugins { id 'com.intershop.gradle.scmversion' version '2.7.2' } scm { version { type = 'threeDigits' initialVersion = '1.0.0' } } version = scm.version.version

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

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. Using this configuration a lot of the features are no longer available. plugins { id 'com.intershop.gradle.scmversion' version '2.7.2' } 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: ./gradlew publish -PrunOnCI=true -PscmVersionExt=SNAPSHOT ./gradlew publish -PrunOnCI=true -PscmVersionExt=RELEASE After a release it is necessary to change the version manually.

The integration tests use test repositories. Therefore, it is necessary to specify project properties for the test execution. 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 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

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 http://www.apache.org/licenses/LICENSE-2.0 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.