How to configure GitVersion to work with 'Trunk Based Development' using 'Branch for Release'

[sheppyh]

Edit: See how to configure this properly here: #3357 (comment)

TLDR: How do I/is it possible to configure GitVersion to work with: https://trunkbaseddevelopment.com/branch-for-release/ when tags only exist on release branches.

Describe the bug
GitVersion ignores tags on release branches, so main/develop are not showing the correct version.
It appears "tracks-release-branches" does nothing - i.e. setting this to true on the master branch doesn't fix the issue.
We use trunk-based development with branch for release - see here: https://trunkbaseddevelopment.com/branch-for-release/
So at some point in development we branch off master into, for example, release-1.0.x and start preparing a release.
All bug fixes are made on master, then cherry-picked into the release branch. These changes are never merged back to master.
When a release is ready, the latest commit on the release branch is tagged, for example 1.0.0

Expected Behavior

At this point, I expect master branch to be showing version 1.1.0

Actual Behavior

Master branch is showing version 0.1.0

Possible Fix

Fix/cause unknown - could be my configuration (this is reproducible with default config, and any configuration I can think of)

Steps to Reproduce

1. Create a test repository, create a README.md
2. git commit -m "Initial commit"
3. Add a file
4. git commit -m "feat: FirstFeat"
5. git branch release-1.0.x
6. git checkout master
7. Add another file
8. git commit -m "fix: FirstFix"
9. git checkout release-1.0.x
10. git cherry-pick
11. git tag 1.0.0

Context

Implement gitversion for trunk-based development using Branch for release. Allow developers to continue committing to master by cherry-picking fixes from master into release branch when preparing a release. Tag release branch - master branch shows correct version for next release.

Your Environment

Multiple versions tested, exists in 5.12.0

• Version Used: 5.12.0
• Operating System and version (Windows 10, Ubuntu 18.04): Windows Server 2016
• Link to your project: N/A
• Link to your CI build (if appropriate): N/A

gitversion /diag:

INFO [01/30/23 15:52:12:53] Dumping commit graph: 
INFO [01/30/23 15:52:12:65] * 9406344 2 minutes ago  (tag: 1.0.0, release-1.0.x)
| * 04f5a1c 3 minutes ago  (HEAD -> master)
|/  
* 0e56ce9 4 minutes ago 
* 358ef40 4 minutes ago 

INFO [01/30/23 15:52:12:65] Working directory: C:\Users\admin-hjohn\Desktop\Git\VersionControlTesting4
INFO [01/30/23 15:52:12:73] Branch from build environment: 
INFO [01/30/23 15:52:12:74] Project root is: C:\Users\admin-hjohn\Desktop\Git\VersionControlTesting4\
INFO [01/30/23 15:52:12:74] DotGit directory is: C:\Users\admin-hjohn\Desktop\Git\VersionControlTesting4\.git
INFO [01/30/23 15:52:12:82] Using latest commit on specified branch
INFO [01/30/23 15:52:12:90] Running against branch: master (04f5a1c fix: FirstFix)
INFO [01/30/23 15:52:12:90] Begin: Calculating base versions
  INFO [01/30/23 15:52:12:92] Fallback base version: 0.1.0 with commit count source 358ef4054a7e6d992131d052fe97708e9eab1eaa
  INFO [01/30/23 15:52:13:06] Found multiple base versions which will produce the same SemVer (0.1.0), taking oldest source for commit counting (Fallback base version)
  INFO [01/30/23 15:52:13:06] Base version used: Fallback base version: 0.1.0 with commit count source 358ef4054a7e6d992131d052fe97708e9eab1eaa
  INFO [01/30/23 15:52:13:06] End: Calculating base versions (Took: 162.88ms)
  INFO [01/30/23 15:52:13:07] 2 commits found between 358ef40 Initial commit and 04f5a1c fix: FirstFix
  INFO [01/30/23 15:52:13:07] Skipping version increment
  INFO [01/30/23 15:52:13:07] 2 commits found between 358ef40 Initial commit and 04f5a1c fix: FirstFix
Executing GenerateSetVersionMessage for 'LocalBuild'.

Executing GenerateBuildLogOutput for 'LocalBuild'.
{
  "Major": 0,
  "Minor": 1,
  "Patch": 0,

[HHobeck]

I think this issue is duplicated or at least related to #1789 track-merge-target in branch config not working.

[sheppyh]

I think this issue is duplicated or at least related to #1789 track-merge-target in branch config not working.

Thanks @HHobeck i see the similarities here but think it’s a different issue.

In the referenced case the config parameter is “track-merge-target” and this looks for merges:

track-merge-target

Strategy which will look for tagged merge commits directly off the current branch. For example develop → release/1.0.0 → merge into master and tag 1.0.0. The tag is not on develop, but develop should be version 1.0.0 now.

The difference is that trunk based development with release branch doesn’t use merges - instead it uses cherry pick - so this is the wrong config parameter to use.

I’m not fluent in all the branching strategies, but from my limited exposure, I think this issue could actually be simpler, summarised as:

In all cases, if a commit is tagged on a release branch it is a release. If v1.0.0 has been released, we should now be developing v1.1.0. However, the tags on release branches are always ignored.

[HHobeck]

Maybe you are right and your scenario is different. But the root course of your issue is the same like the bug I have mentioned IMO (please see my comment here).

[HHobeck]

Actually we have so many workflows out there and everyone has a different expectation/view on how the semantic version number should be generated. Also your scenario is very special and I see it (with cherry picking) the first time.

I see GitVersion as a cooking machine where the user is responsible providing the correct ingredients.

What I'm trieng to say is: It might be very helpful to try first and ask question to identify the route course and not just create a bug if your (custom) workflow not working from beginning. If you have a workflow which cannot be mapped and you need a new mechanism then please feel free and contribute with a PR or create feature improvement issue or discussion.

See also the comment from asbjornu here:

At the end to come back to the problem of the author it is just important to detect the tagged commits on branches which are marked with IsMainline=true independent of its name.

From my understanding, Mainline [aka Trunkbase] should not require tags at all. See #950 for its initial implementation in GitVersion.

At the end I don't know if your workflow can be mapped to GitVersion or not (defining the ingredients). It is hard work to answer and this is something you need to do.

[HHobeck]

Could you please rename this issue like: GitVersion ignores tags on release branches when marked as IsMainline=true?

[sheppyh]

Also your scenario is very special and I see it (with cherry picking) the first time.
your (custom) workflow

I'm surprised this is a very special scenario, which it might be, but it's definitely not custom. I don't spend enough of my time writing software as an IT Manager, so I look for existing workflows to adopt rather than write my own custom. Here's why I don't think it's special:

1. Atlassian (BitBucket developers) have an article about "Gitflow workflow" and have the following text in the introduction:

Gitflow has fallen in popularity in favor of trunk-based workflows, which are now considered best practices for modern continuous software development and DevOps practices.

2. Searching Google for "trunk based development" takes you to trunkbaseddevelopment.com, which has a sub-heading for branch for release. This is the exact workflow I'm using and struggling to define the ingredients for.
3. The branch for release article references a Google presentation showing that they also cherry pick from trunk/mainline to release branch, as per the TBD with release branch workflow.

Maybe it's not commonly used, but it seems odd to me that I've been strongly directed to this workflow by significant sources when researching the topic.

It might be very helpful to try first and ask question to identify the route course and not just create a bug

Apologies if I went about this the wrong way. However, I would point out, the very first line of my issue asks the question "can I/how do I configure for this workflow", and I found the bug template useful to describe my problem - and believed it was a bug

I still believe it to be one (either in code or documentation), that neither a tagged commit on a defined release branch counts as a source for version incrementing by default, and tracks-release-branch doesn't give this behavior either.

Additionally, the tracks-release-branch documentation doesn't explain what it does, and the naming of the parameter doesn't match how it's described ("Indicates this branch config represents develop in GitFlow.") - a better parameter name for this description would be "is-develop-branch". Looking at history, it appears this was once the case, so if this isn't a bug, perhaps my confusion is with the documentation describing what tracks-release-branches does - after it was renamed in the past.

As an aside - is there any workflow that exists where you would tag a commit with a version number on a release branch and it not be an indication of a release? If not, perhaps this is the feature request I should be raising?

Happy to work with you on the best way forward, just a matter of identifying that. I can write a little C#, so if we agree on the way forward I'll do my best to raise a PR. Hope you understand my confusion and how I got here.

[sheppyh]

I did some research into the renaming of is-develop to tracks-release-branches and found the PR was created from an issue describing the exact same workflow we're discussing here:

#988

You created a branch release/0.10 with some commits. Thus, the master branch (marked with is-develop) should pick up the version number 0.10.

In my case, I cannot configure gitversion to achieve this behavior.

I'm just setting up an environment to see if I can write some test cases for this.

[HHobeck]

Also your scenario is very special and I see it (with cherry picking) the first time.
your (custom) workflow

I'm surprised this is a very special scenario, which it might be, but it's definitely not custom. I don't spend enough of my time writing software as an IT Manager, so I look for existing workflows to adopt rather than write my own custom. Here's why I don't think it's special:

Okay maybe I haven't used the correct words sorry for the confusion. Your scenario is maybe not custom and widely used in the community. For me it is a new workflow which I'm not used to and also the default supported workflow of GitVersion is the gitflow and the github workflow (please see gitflow and github sequence diagram). Of course GitVersion is highly configurable and can be (or at least should be able to be) adapted to any other workflows out there (including custom ones ;)). If I'm saying custom then I mean it's not the default workflow in GitVersion and the configuration file needs to be adapted from user point of view.

BTW: In GitVersion we have also a Mainline option which reflects in my opinion the trunk-base development workflow but without any tagging. So you see if your are talking from the trunk-base workflow nine of ten persons have a different expectation how it should be working.

[HHobeck]

Apologies if I went about this the wrong way. However, I would point out, the very first line of my issue asks the question "can I/how do I configure for this workflow", and I found the bug template useful to describe my problem - and believed it was a bug

I still believe it to be one (either in code or documentation), that neither a tagged commit on a defined release branch counts as a source for version incrementing by default, and tracks-release-branch doesn't give this behavior either.

Yes no problem. Just want to point out that we are all doing our best and a bug has a negative implication. It's hard work to analyses the behavior of custom or different workflows and find out what the root course might be. Anyway in your scenario I think you are right and we have a bug. I think the is-mainline option is the right option for you.

Additionally, the tracks-release-branch documentation doesn't explain what it does, and the naming of the parameter doesn't match how it's described ("Indicates this branch config represents develop in GitFlow.") - a better parameter name for this description would be "is-develop-branch". Looking at history, it appears this was once the case, so if this isn't a bug, perhaps my confusion is with the documentation describing what tracks-release-branches does - after it was renamed in the past.

Yep I agree the documentation gives not really a good explanation. The tracks-release-branch option e.g. on the develop branch looks at the existing branches (with the name release) and uses the version as a base version to calculating the next one.

As an aside - is there any workflow that exists where you would tag a commit with a version number on a release branch and it not be an indication of a release? If not, perhaps this is the feature request I should be raising?

The only scenario I know is for beta releases. Here you are tagging the beta version to increment the pre-release tag to the next one. But this process is just within the release/x.x.x branch and doesn't affect any other branches like main (of course because it is not a release to manufacturing (RTM)). I don't think that we need a new mechanism to fullfill your requirements.

[HHobeck]

Happy to work with you on the best way forward, just a matter of identifying that. I can write a little C#, so if we agree on the way forward I'll do my best to raise a PR. Hope you understand my confusion and how I got here.

Thank you very much for your input. I'm very interested in standard workflows out there and would like to integrate (all of them) into GitVersion. Therefor I have created a new feature issue #3305. Please have a look and let me know what you think.

[sheppyh]

Okay, I've figured it out, and trunk-based development with release branches is easily supportable with minimal config changes.

The key was in the following PR: Bump develop when release branch created #832

Develop gets bumped when a release branch is created, therefore tags on the release branch are not actually necessary to get that bump. Two major things I was doing wrong:

1. Incorrect release branch naming
   release-1.0.x is not recognised as a correct version, whilst nice to say to a human "this branch contains releases for the major/minor 1.0.x" - it's not understood by GitVersion in the same way. You need to name the branch release-1.0.0 and live with the fact that you will have a 1.0.1 release inside that branch. (Possible feature request, but minor issue)

2. The develop branch is bumped at next commit - not immediately
   I expected to return to develop after branching into release-1.0.0 (and tagging in there) and see immediately the version of develop as 1.1.0-alpha. However, this only happens after the first commit in develop after branching. (Another possible feature request - but again, also minor issue).
   This is shown clearly in the docs and I missed it:
   

In the end, I have just disabled the main branch, and set regex for develop to match master/main, and removed release as a source branch for release. Finally I set release branch into ContinuousDeployment so each beta version has its own PreReleaseNumber.

Here's the config I've settled on:

branches:
  main: 
    # Match nothing
    regex: ^\b$
  develop:
    # Development is done on master
    regex: ^master$|^main$
  release:
    source-branches:
      - main
    mode: ContinuousDeployment

[sheppyh]

Thank you very much for your input. I'm very interested in standard workflows out there and would like to integrate (all of them) into GitVersion. Therefor I have created a new feature issue #3305. Please have a look and let me know what you think).

I think this is a brilliant idea. It would also open up for the community to add/suggest built-in templates as pull requests in future. For example, I could suggest the above config as a "trunk-based development with release branches" workflow and others can easily make use of it.

[sheppyh]

Thanks for your help @HHobeck - your comments pushed me to find the solution in the end. This issue can be closed unless you still think we've identified a bug rather than my misinterpretation of the docs after reviewing how I fixed it:

Anyway in your scenario I think you are right and we have a bug.

This case might also have some useful information to improve the tracks-release-branches parameter description in the docs - and possibly some feature requests but I'm not sure if these are just my preferences/nice to haves.

[HHobeck]

Develop gets bumped when a release branch is created, therefore tags on the release branch are not actually necessary to get that bump. Two major things I was doing wrong:

1. Incorrect release branch naming
   release-1.0.x is not recognised as a correct version, whilst nice to say to a human "this branch contains releases for the major/minor 1.0.x" - it's not understood by GitVersion in the same way. You need to name the branch release-1.0.0 and live with the fact that you will have a 1.0.1 release inside that branch. (Possible feature request, but minor issue)

In version 6.x we have introduced a semantic-version-format option which can be set to Loose for your scenario. Creating a release branch/1.1 for instance yields to the semantic version 1.1.0.

2. The develop branch is bumped at next commit - not immediately
   I expected to return to develop after branching into release-1.0.0 (and tagging in there) and see immediately the version of develop as 1.1.0-alpha. However, this only happens after the first commit in develop after branching. (Another possible feature request - but again, also minor issue).

This behavior has been fixed in the version 6.x. Please have a look on the pre release version 6.0.0-alpha.1 or check the code on main branch.

This is shown clearly in the docs and I missed it:

In the end, I have just disabled the main branch, and set regex for develop to match master/main, and removed release as a source branch for release. Finally I set release branch into ContinuousDeployment so each beta version has its own PreReleaseNumber.

Nice catch to reuse the develop configuration for your main branch. Good to know that you don't need any tags on the release branch.

[HHobeck]

Thanks for your help @HHobeck - your comments pushed me to find the solution in the end. This issue can be closed unless you still think we've identified a bug rather than my misinterpretation of the docs after reviewing how I fixed it:

Anyway in your scenario I think you are right and we have a bug.

This case might also have some useful information to improve the tracks-release-branches parameter description in the docs - and possibly some feature requests but I'm not sure if these are just my preferences/nice to haves.

Great. It's a pleasure to help you. I think we don't need a bug for enhancing documentation. Thus I'm going to close it.