Introduction
\n \n \nThis plugin can be used to determine the next release version based on previous tags and the commit messages used.
It can also be used to get the current version. :warning: By default only annotated tag are supported, to support non annotated tag you must use an option to activate this feature (see below).:warning: It calculates the version number based on the format of the commit message.
The commit message format used is conventional commits.
Getting started
\n \n \nThis plugin can be used in a pipeline in a stage or the environment block. Some examples of this in use are:
\nIn the environment block
\n \n \npipeline {\n agent any\n\n environment {\n CURRENT_VERSION = currentVersion()\n NEXT_VERSION = nextVersion()\n }\n\n stages {\n stage('Hello') {\n steps {\n echo \"current vesion = ${CURRENT_VERSION}\"\n echo \"next version = ${NEXT_VERSION}\"\n }\n }\n }\n}\n
\n In a scripted Pipeline
\n \n \ndef NEXT_VERSION\nnode {\n stage('Get next version ...') {\n CURRENT_VERSION=currentVersion()\n echo \"Current version: $CURRENT_VERSION\" \n NEXT_VERSION=nextVersion()\n echo \"Next version : $NEXT_VERSION\"\n }\n stage ('Release') {\n sh \"mvn release:prepare -DreleaseVersion=$NEXT_VERSION\"\n sh 'mvn release:perform'\n }\n}
\n Using Optional Parameters
\n \n \nThe plugin provides provision to use optional parameters for support of build metadata, pre-release information, settings the start tag, etc. :warning: These parameters are only for the nextVersion step ! \n
Build Metadata
\n \n \nbuildMetadata
an optional parameter can be added as follows:
pipeline {\n agent any\n environment {\n NEXT_VERSION = nextVersion(buildMetadata: \"$env.BUILD_NUMBER\")\n }\n stages {\n stage('Hello') {\n steps {\n echo \"next version = ${NEXT_VERSION}\"\n }\n }\n }\n}\n
\n Assuming next version is 1.1.0
. The pipeline will output :next version = 1.1.0+001
Use with prerelease information
\n \n \nFor a 1.0.0
existing version the following code :
pipeline {\n agent any\n\n environment {\n NEXT_VERSION = nextVersion(preRelease: 'alpha')\n }\n\n stages {\n stage('Hello') {\n steps {\n echo \"next version = ${NEXT_VERSION}\"\n }\n }\n }\n}\n
\n Will display :next version = 1.1.0-alpha
Prerelease possible combinations
\n \n \nThere are three options to manipulate the prerelease option :
\n- \n
- the name of the prerelease ➡️
preRelease
\n - keep the existing prerelease (default false) ➡️
preservePrelease
\n - increment the existing prerelease (default false) ➡️
incrementPreRelease
\n
The table below resume the combined use of these options and the result:
\ncurrent version | \nBreaking change commit msg | \nFeature commit msg | \nOther or empty commit msg | \nprerelease | \npreservePreRelease | \nincrementPreRelease | \nOutput | \n
---|---|---|---|---|---|---|---|
0.1.0 | \nX | \n- | \n- | \n- | \n- | \n- | \n1.0.0 | \n
0.1.0 | \n- | \nX | \n- | \n- | \n- | \n- | \n0.2.0 | \n
0.1.0 | \n- | \n- | \nX | \n- | \n- | \n- | \n0.1.1 | \n
0.1.0 | \nX | \n- | \n- | \nalpha | \n- | \n- | \n1.0.0-alpha | \n
0.1.0 | \n- | \nX | \n- | \nalpha | \n- | \n- | \n0.2.0-alpha | \n
0.1.0 | \n- | \n- | \nX | \nalpha | \n- | \n- | \n0.1.1-alpha | \n
1.0.0-alpha | \n- | \n- | \n- | \n- | \n- | \n- | \n1.0.0 | \n
0.1.0-alpha | \n- | \n- | \n- | \n- | \n- | \n- | \n0.1.0 | \n
0.1.1-alpha | \n- | \n- | \n- | \n- | \n- | \n- | \n0.1.1 | \n
0.1.0-alpha | \nX | \n- | \n- | \n- | \nX | \n- | \n1.0.0-alpha | \n
0.1.0-alpha | \n- | \nX | \n- | \n- | \nX | \n- | \n0.2.0-alpha | \n
0.1.0-alpha | \n- | \n- | \nX | \n- | \nX | \n- | \n0.1.1-alpha | \n
0.1.0-alpha | \n- | \n- | \nX | \n- | \nX | \nX | \n0.1.1-alpha.1 | \n
0.1.0-alpha | \nX | \n- | \n- | \nbeta | \n- | \n- | \n1.0.0-beta | \n
0.1.0-alpha | \n- | \nX | \n- | \nbeta | \n- | \n- | \n0.2.0-beta | \n
0.1.0-alpha | \n- | \n- | \nX | \nbeta | \n- | \n- | \n0.1.1-beta | \n
Write next version in the configuration file (pom.xml, package.json)
\n \n \nThe optional parameter writeVersion
allow writing back to the file the next calculated version.
\n
The supported configurations files :
\n- \n
- pom.xml (Maven) : need the Maven CLI in the path, \n
- package.json (NPM) : need the Npm CLI in the path, \n
- chart.yaml (Helm), \n
- build.gradle / gradle.properties (Gradle), \n
- setup.py / setup.cfg / pyproject.toml (Python), \n
- go.mod (GoLang). \n
Example of use : With a project with a package.json as follows :
\n{\n \"name\": \"conventional-commits-plugin-example-npm\",\n \"version\": \"1.0.0\",\n \"description\": \"Npm example project\"\n}
\n The following pipeline with a commit with a commit message like feat: my cool feature:
\npipeline {\n agent any\n environment {\n NEXT_VERSION = nextVersion(writeVersion: true)\n }\n stages {\n stage('Hello') {\n steps {\n echo \"next version = ${NEXT_VERSION}\"\n }\n }\n }\n}
\n Will update the package.json as follows :
\n{\n \"name\": \"conventional-commits-plugin-example-npm\",\n \"version\": \"1.1.0\",\n \"description\": \"Npm example project\"\n}
\n Issues
\n \n \nReport issues and enhancements in the Github issue tracker.
\nContributing
\n \n \nWe encourage community contributions for this project! For more information on how to contribute to this project, see the contribution guidelines
\nLICENSE
\n \n \nLicensed under MIT, see LICENSE
\n