Introducing the Conventional Commits Plugin for Jenkins
The conventional commits plugin is a Google Summer of Code project. Special thanks to the mentors Gareth Evans, Kristin Whetstone, Olivier Vernin and Allan Burdajewicz.
What are Conventional Commits
According to the official website, conventonal commits are, "A specification for adding human and machine readable meaning to commit messages."
Conventional commits are a lightweight convention on top of commit messages.
The following table shows major structural elements offered by the conventional commits convention.
| Structural Element | Example |
|---|---|
Chore |
|
Fix |
|
Feat |
|
Breaking Change |
|
Why Conventional Commits
As the CI/CD world is moving more towards complete automation and minimal human interaction, the ability to fully automate a release is desired. Conventional Commits enable the use of automated systems on top of commit messages. These systems can "truly" automate a release with almost no human interaction.
The convention dovetails with semantic versioning.
Let’s take an example, a maven project is currently versioned at 1.2.0.
The following table shows how conventional commits would bump the version depending on the type of the commit.
| Commit Message | Version Bump | SemVer Equivalent |
|---|---|---|
|
|
No version bump |
|
|
Increment in the patch version |
|
|
Increment in the minor version |
|
|
Increment in the major version |
The Conventional Commits Plugin
The conventional commits plugin is a Jenkins plugin to programatically determine the next semantic version of a git repository using:
-
Last tagged version
-
Commit message log
-
Current version of the project
How it works?
The plugin will read the commit messages from the latest tag or the current version of the project till the latest commit. Using this information it will determine what would be the next semantic Version for that particular project.
Supported Project Types?
Currently the plugin can read the current version from various configuration files of the following project types:
| Project Type | Configuration File(s) Read |
|---|---|
Maven |
pom.xml |
Gradle |
build.gradle |
Make |
Makefile |
Python |
setup.py setup.cfg pyproject.toml |
Helm |
Charts.yml |
Node (NPM) |
package.json |
How to request a project type support?
Please feel free to open an issue on the GitHub repository of the plugin.
How to use the plugin
Recommended way of using the plugin is to add a step in a Jenkins Pipeline Project.
nextVersion() is the pipeline step to be used.
For example:
pipeline {
agent any
environment {
NEXT_VERSION = nextVersion()
}
stages {
stage('Hello') {
steps {
echo "next version = ${NEXT_VERSION}"
}
}
}
}Tip: The pipeline step can also be generated with the help of the Snippet Generator. Please select "nextVersion" in the Sample Step drop down and then click on "Generate Pipeline Snippet"
The plugin is released on every feature using JEP-229.
The plugin is available to download from the plugins site.
Next Steps
-
Support for pre-release information. Example:
1.0.0-alpha,1.0.0-beta, etc -
Support for build metadata. Example:
1.0.0-beta+exp.sha.5114f85 -
Optionally writing the calcuated "Next Version" into the project’s configuration file. Example:
pom.xmlfor a maven project,setup.pyfor python.
Feedback
We would love to hear your feedback & suggestions for the plugin.
Please reach out on the plugin’s GitHub repository, the Gitter channel or start a discussion on community.jenkins.io.
|
Aditya Srivastava
Aditya is a curiosity driven individual striving to find ingenious solutions to real-world problems. He is an open-source enthusiast and a life long learner. |