How can I bump patch version?

[vitalii-dubovoi]

Hi guys, maybe I missed some core concepts of semver and semantic-version action, but I don't understand how to bump a patch version.
As I see from the documentation it's automatically incremented from the last tag in history

But how can it be incremented if, for example, a new pull request is merged to the main branch?

We have a NuGet package and whenever a new branch is merged it should update the patch version number, but I don't understand how to achieve it.

Thanks

[PaulHatch]

When this action runs it first looks for the most recent version tag, once that is found all the commits since that tag are collected and evaluated to determine the next "version type".

• If there are any commit messages that match the major_pattern, the version type is major
• Otherwise, if there are any commit messages that match the minor_pattern, the version type is minor
• Otherwise the version type is patch

This type is then used to increment the version exactly one increment forward. The increment count (which is not part of the version, but can be used to create a prerelease tag or as a build number in the four-number versions used sometimes like in .NET assembly versions) is set to the number of commits since the version changed.

The intent here is the the developer making the change knows and is in the best position to indicate whether a change is breaking or not, and by indicating this in the commit the version can be determined correctly regardless of whatever other changes are included in a version. You should be able to do this with a merge commit message as well. Alternatively if you want to do something different you could fork and extend the providers, the DefaultVersionClassifier for example. These are designed to be as easy to customize as possible to work into your specific setup.

[vitalii-dubovoi]

Hi @PaulHatch, sorry but I still can't get how to bump a patch version.

I created a repo to check some cases, https://github.com/vitalii-dubovoy/version-bump that uses paulhatch/semantic-version@v4 action and format: "${major}.${minor}.${patch}-test${increment}"

I have tagged the main branch with v1.0.0 tag and pushed it to the repo the second action run gives me the 1.0.1-test2 version output. Increment 2 it's actually the number of commits since the last major or minor updates.

I created a new branch, update01, where the version is Version is 1.0.1+3. After it, I merged this branch with the main and got - 1.0.1-test4 during the build. Maybe I'm mistaken but as I understand the action should have bumped the version to 1.0.2-test4.

You mentioned:

If there are any commit messages that match the major_pattern, the version type is major
Otherwise, if there are any commit messages that match the minor_pattern, the version type is minor
Otherwise the version type is patch

I really can't get what is otherwise for the patch, if the increment part is bumped by each commit, what should I do in my example to increase patch version?

Thanks,

[PaulHatch]

Hey @vitalii-dubovoy, no problem. What you need to do is mark the release. The next release after the tag will be incremented. If it isn't a major or minor release, it will be a "patch" type by default.

Think of it in terms of being a customer/consumer of your project; as a customer if I'm on version 1.0.0 I'd expect it to go to 1.0.1, 1.1.0, or 2.0.0. If I see 1.0.2 I'm gonna think I missed a version. In general in most build systems incrementing on every build is trivial, but it creates these gaps whenever a version with more than one commit is released, so that's the purpose of this action. A lot of small projects do get released as a new version on every commit, so for those cases there's a "bump each commit option", but in general the idea is that the the version is only being updated after a release.

There are currently two ways to make a release, one is to use a tag, which is the default. (I recommend this approach even if you aren't using this action, unless you specifically need to do something like support multiple versions simultaneously released/bug fixes on older versions.) In this mode the commit history is searched for a tag to find the last version, that tag does two things--first it provides the version to be incremented, second it identifies the starting commit for this version, commits after this will be checked to see if they are major or minor, and the total number of commits in the release is used to determine the increment value.

The other mode does the same thing using branches, and is enabled by setting the useBranches option (available in version 5). There are a few edge cases when using branches that may produce some unexpected behavior if you have complicated merges. A lot of this is resolved by sorting by the ref name rather than the order, so as long as you're creating a branch for a release, incrementing the version (rather than jumping backwards for some reason for example) and following some type of git-flow like pattern you should be ok most of the time. You can see the relevant code here.

In your example, the branch merge is doing nothing, tag version mode is enabled by default so it is looking for the tag and finds v1.0.0. There is a commit after the tag which matches the pattern MAJOR, so the commit type is major, resulting in v2.0.0. Once you create a v2.0.0 tag, the next version will be v2.0.1. If you then tag a commit v2.0.1 the next will be v2.0.2 and so on until a major or minor commit causes the version type to change.

Also note that the version format is only setting the output version string, the version tag (or branch format) is a different thing, you can customize it by setting the prefix, namespace, or namespace separator.

I recommend upgrading to version 5. The prerelease has been pretty stable so far, I'm just finishing a couple of open items before releasing, but I don't think there are any regressions.

[vitalii-dubovoi]

@PaulHatch Hello, thank you for clarifying this