Support automatic semVer with conventionalCommits

[agaudreault]

Allow the developers to use the SemVer scheme with the CD workflow. It is possible to fully generate a semantic version based on the commit message and history.

For instance, if the last semantic Tag in the current branch is 1.0.0 and a commit is made starting with feat:, the next release will be 1.1.0. The current JEP-229 generate version numbers such as {digit}.v{hash} that lose all meaning of changes. When a Jenkins maintainers needs to bump a plugin, it is impossible to know at a glance if it contains breaking change or not. The developers will have to do a comparison of the git history and try to find any breaking change. The proposed way to do that is to keep the major.minor part of the version manual, which defeat the purpose of automating the version and release process.

Generating a semantic version number based on commit history has many advantages:

• Explicit developer intent in the commit message
• Allows you to know if the version contains breaking changes, new features or only fixes.
• Automatic versioning without manual changes in code
• Compatible with continuous delivery and "fix forward" workflow. New version can be generated and released at each commit into main branches.
• Compatible with a wide range of tools analyzing dependencies and using version range (Dependabot, Renovate, Sonatype IQ Server, etc.)
• Deterministic version. (The git history and tag should not change on remote branches)
• Semver allows to add metadata to version
• Configurable. Maintainers control the convention while the CI control the version.

The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.

Tools such as Semantic Release offers many libraries to perform the automation based on existing and widely adopted conventions. The library also allows maintainers to customize release rules of their projects for their needs instead of forcing them in a box. The CI can still enforce some configuration by merging the 2 with a precedence order.

Suggested version scheme would be

Use case	current (JEP-229)	Proposal
general	{history_depth}.v{commit_hash} (0.vabcd1234) semver: 🚫	{semver}+{commit_hash} (0.0.0+abcd1234) semver: ✅
manual prefix	{prefix}.{history_depth}.v{commit_hash} (0.0.0.vabcd1234) semver: 🚫	N/A controled by commit messages (0.0.0+abcd1234) semver: ✅
wrapped components	{wrapped_semver}-{history_depth}.v{commit_hash} (1.0.0-0.vabcd1234) semver: ✅	{wrapped_semver}-{semver}+{commit_hash} (1.0.0-0.0.0+abcd1234) semver: ✅

Related to jenkinsci/jep#383 (comment)

[timja]

FWIW it is possible to use semantic release with the CD process, there's an example here:
https://github.com/jenkinsci/conventional-commits-plugin/blob/main/.github/workflows/cd.yaml

But then that requires conventional commits which aren't really used in the Jenkins ecosystem

[agaudreault]

From what I read, using https://github.com/jenkins-x-plugins/jx-release-version would conflict with what is documented in https://www.jenkins.io/doc/developer/publishing/releasing-cd/. The conventional-commits-plugin is omitting -Dchangelist.format=%d.v%s in maven.config and ignoring the JEP-229 version. I am curious to have the opinion of @garethjevans to know why he opted-out of the new scheme with CD.

I think it would be good to document that approach as an option to CD. It would also require some settings on the repository, such as Squash & Merge option to be enforced, and a status checks to have https://github.com/zeke/semantic-pull-requests or something similar enabled and configured. @jglick

[garethjevans]

Hi @agaudreault-jive, the reason we went with jx-release-version in the conventional commits plugin was that we felt that there is value in providing proper semantic versions for releases. The conventional commits plugin is designed to do just that - its just that we have a dog fooding issue trying to get the plugin to trigger from github actions for the plugin release.

[jglick]

I could not recommend the approach taken in conventional-commits-plugin as it runs only inside the GitHub Action workflow performing the release; builds from source (including plugin-compat-tester and various developer workflows) will use some unrelated version number. This makes for messier Maven usage particularly in the case of components which expose an API or which might otherwise become a Maven dependency. Someone who cares about semantic versioning could write a variant of https://github.com/jenkinsci/incrementals-tools/blob/5e41c4d8dbb0d5ff0b882310f8805b6e4d792281/git-changelist-maven-extension/src/main/java/io/jenkins/tools/incrementals/git_changelist_maven_extension/Main.java#L79-L133 which follows Conventional Commit semantics walking history on the first ancestor (to the root, or some base commit with an initial version also specified in .mvn/maven.config) so that

mvn -Dset.changelist install

would produce the desired versioned artifact. In that case jenkins-maven-cd-action would probably handle it fine, and I expect you could in fact use the stock https://github.com/jenkinsci/.github/blob/master/workflow-templates/cd.yaml.

[jglick]

Tried to transfer this to https://github.com/jenkinsci/incrementals-tools/issues but that seems impossible as it is in a distinct GitHub organization?

[timja]

Yeah unfortunately you can't transfer across organisations.

multi-organisation places normally work around it with a bot which re-reports it with a backlink and a comment on the side it was 'transferred' from.