GSoC

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

chore: improve logging

Fix

fix: minor bug fix

Feat

feat: add a new feature

Breaking Change

BREAKING CHANGE: reimplement

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

chore: improve logging

1.2.01.2.0

No version bump

fix: minor bug fix

1.2.01.2.1

Increment in the patch version

feat: add a new feature

1.2.01.3.0

Increment in the minor version

BREAKING CHANGE: reimplement

1.2.02.0.0

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.

Demo

You can watch the plugin in action in a demo presented at the GSoC Midterm Presentations

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.xml for a maven project, setup.py for 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.

About the Author
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.

Discuss