v5.3.0 always looks for tags created from the branch

[impks27]

v5.3.0 always looks for tags created from the branch.
By default it should consider last matching tag on the repo. Right now it's always making an increment to tag from the particular branch.

Is this expected behaviour?

[PaulHatch]

Yes, or more specifically it always looks at the current HEAD unless you set the branch explicitly (not recommended 99% of the time).

So "current" is found using git' rev-parse HEAD, then this command is used to find the tag:

git for-each-ref --sort=-v:*refname --format=%(refname:short) --merged=${current} ${refPrefixPattern}${releasePattern}

If it looked at the entire repository you'd get some very strange behavior, especially when re-running older builds.

[impks27]

Thanks for the reply. It's an awesome action.
Does this support releasing from multiple branches?
For e.g.
If I use release branches for each release
REL2023.10.0
REL2023.11.0

Will each branch start with 0.0.1? I assume no, as it could cause scmtag exists issue.

How to support this case using this action?

[PaulHatch]

Thanks, yes, there is a new branch support feature just added a few weeks ago (#76). The term branches in this context can be a bit overloaded so let me define these first:

• There is a branch parameter, referenced above, this allows you to explicitly get a version for a particular branch (or commit). This has been present from the start, but I don't think this is useful at all to be honest, I'm considering removing it. Aside from the name it doesn't really have anything to do with "branch support"
• There is a use_branches option which is deprecated now and will be removed in version 6. This literally just uses the branch name instead of the tag. This works in certain limited cases but is problematic once you start merging branches, since branch commits aren't fixed.
• Finally there is the latest option version_from_branch, if you want to version from branches, this is the option you want to use.

What the version_from_branch option does when enabled is look at the name of the currently checked out branch and if it ends with either a {major} or {major}.{minor} pattern (e.g. v1 or v1.2) it will always use those values are the major/minor version, considering only tags which match that version. It will also downgrade commit message increments so that the predicted version does not exceed the branch version, so a MAJOR type commit on a v1 branch will be treated as a minor increment.

In this way you would be able to do things like merge a bug fix into multiple version branches without worrying about the tags present in the commit log for other versions or commit messages causing a conflict with another already published version.

You should tag the commit where that branch is first created in order to get reliable increment numbers, otherwise the action won't know how far back a particular version branch forked from the main trunk, and continue to tag commits when you release them the same as you would without branch support enabled since the action will still look for tags matching the branch version.

Note that in your example it seems that you are specifying the patch as part of the branch name, is the major version supposed to be 2023? If you enable version_from_branch only the the last two numbers at most will be used, so REL2023.10.0 would be interpreted as v10.0.*, so only tags in this range would be considered.

[impks27]

The problem I am facing is when I create tags from feature branches. Same tags are getting created from both feature branches and my pipeline is failing with error SCM tag already exists.

How do I get past this?

Use case is to be able to create tags from different feature branches but follow semantic versioning for the repository

[PaulHatch]

Well the tags need to be unique, I'm not sure what you're using exactly though.

What I mean is imagine you are on master and you are releasing a new version, say 7.0.0. You would create a branch name like release/v7 or release/v7.1 depending on whether you planned to provide ongoing updates for v7.x or v7.0.x. At that point you need to also tag that commit like v7.0.0.

Some time goes by and you want to release an update. You're still on branch release/v7 or release/v7.0, so you build as normal and the action gives you the version 7.0.1, when you decide to release you add that tag. So far nothing has really changed from a normal setup that isn't using branches aside from the creation of the branch.

After you've released 8.0.0 suppose you find a bug in 7.0.1 and want to fix it. This is where the version_from_branch has an effect, depending on how that commit was created. If you simple push a new commit to the branch, that's pretty simple and you won't have any issues regardless. On the other hand if you are doing some more complicated stuff with merges, merging a fix into multiple branches you could run into trouble if the branch ends up including a commit tagged for a later version. Here using version_from_branch ensures that only 7.x commits are considered, and that no commits will cause your version to exceed the one specified by the branch name.

Using branches for versioning is quite an advance use case, most people will not need. I am in the process of writing up a guide which includes a section on choosing a versioning strategy. It is still a work in progress, but might be helpful.

[jerryderry]

Hi, I actually have the same question, but I'm not quite understand your explanation above.

git for-each-ref --sort=-v:*refname --format=%(refname:short) --merged=${current} ${refPrefixPattern}${releasePattern}

This command will only list the tags reachable from current. However, not all tags can be reached from there. Wouldn't it mean conflicting tags will be generated?

Could you also elaborate on this, please?

If it looked at the entire repository you'd get some very strange behavior, especially when re-running older builds.

Why would we have strange behaviour?

My use case is: feature branches will be created, and once a feature is done, the feature branch will be merged back to the main branch, producing a release. There is only one series of version numbers.

[PaulHatch]

This command will only list the tags reachable from current. However, not all tags can be reached from there. Wouldn't it mean conflicting tags will be generated?

Well yes. Maybe I can add some detection for this and print a friendly warning or something.

Why would we have strange behaviour?

You'd randomly pick up versions jumping ahead depending on how other branches had been tagged, the latest version would always be selected. This commit is quite likely not even an ancestor of the current HEAD, so how do we get the commits between them? If you went back and reran a previous build, you'd be trying to use a different tag as the previous tag, etc.

Based on the use case you described you do not need to use the version from branch feature at all, this is an advanced feature intended only for maintaining ongoing updates to previous versions. One thing you may wish to do is to use the branch name or commit hash as part of the version (e.g. v2.0.7-branch-name+1, but this would be done at a higher scope than this action.

e.g.

env:
  VERSION: ${{ steps.version.outputs.major }}.${{ steps.version.outputs.minor }}.${{ steps.version.outputs.patch }}-${{ github.head_ref }}+${{steps.version.outputs.increment}}

This will prevent version conflicts if you have two branches running at the same time which have the same number of commits since the last version tag, which may or may not be a problem for you depending on what else you are doing.

I am going to change this to a conversation, if there's a bug or feature request please open a new issue for it.

[jerryderry]

Thank you for the answer.

You'd randomly pick up versions jumping ahead depending on how other branches had been tagged, the latest version would always be selected.

I would say, this strange behaviour you described is actually what I want. Say feature1 branch got merged, and we have a tag v1.1.0 for release. Then feature2 branch got merged. At this point, I would want a tag v1.2.0, no matter when the two branches were created.

If you went back and reran a previous build, you'd be trying to use a different tag as the previous tag, etc.

You mean some people would want to reran a previous build, and also wants to get the same tag, rather than a different new tag?

Is it fair to say that "wanting to generate the same tag when rerunning a previous build" leads to this design decision? Not to question it, but just curious, because searching tags only from the branch is a bit unexpected for me. To me, it is more "natural" and intuitive to search through the whole collections of tags.

[PaulHatch]

This is the behavior you would see. The process is not too complicated conceptually (I am describing the default/primary behavior here without any options specified):

• Find the highest tag version that matches the expected tag pattern and is reachable from the current commit.
• Extract the version from the tag, that's the "previous version".
• Look at all the commits between the current commit and the last tag, looking for any matching the major or minor.
• The output the predicted new tag which is the last tag incremented by one version according to the tag type detected in the last step.

There are edge cases here and there, for example to handle repos with no tags yet or if the commit itself is tagged, but basically that's it. This action was originally based on a bash script I was using for Jenkins a long time ago, which is available here if that's of any help.

If you merge a feature branch back to your master branch, the version will reflect the new commits when you run it on the master branch. If those commits are already tagged...well that's a bit weird to tag an unmerged feature branch, but that would be reflected also. You can just forget the merges/branches exist and just consider the commits between the last tag and the current commit.

You mean some people would want to reran a previous build, and also wants to get the same tag, rather than a different new tag?

Yes, so long as you didn't go back and tag a commit prior to the commit being rebuild, a re-run will generate the same tag. That's really more of a side effect of the version predicted being deterministic than an original requirement, but also something desirable.

I should note that you can fork this action and relatively easily customize the behavior if you wish, I rewrote the action from scratch at one point specifically to make this easier. You could for example replace the LastReleaseResolver which has just a single method to implement:

export interface LastReleaseResolver {
  ResolveAsync(current: string, tagFormatter: TagFormatter): Promise<ReleaseInformation>;
}

I mostly had in mind cases where people wanted to incorporate external sources of information into the versioning, but you can put whatever logic you want and replace the DefaultLastReleaseResolver and the rest of the action will use this in the pipeline described above.