Prevent decrementation of versions on the develop branch

[bitbonk]

I am trying to adhere the default branching and release model suggested by GitVersion with an almost empty GitVersion.yml.
It only contains next-version: 1.0.

I have a release preparation branch (e.g. release\1.0.0) that tends to live for a longer period of time because
it will be used to create all the beta releases for that version (e.g. 1.0.0-beta1, 1.0.0-beta5 etc.) before it eventually
will me merged into main which trigger the final release.
I was under the impression that this is a good way to handle prereleases in the default GitVersion flow.

My problem now is that GitVersion continuously increments and decrements
the minor version for the develop branch, even though there has not been a final release of the 1.0.0 version yet.
But I really do not want the versions to be decremented on develop because all CI build results (alpha nuget packages)
made for commits of develop are pushed to a "nightly" package feed and consumers would need to downgrade
to get a newer alpha version.

So how can I prevent this continuous incrementation and decrementation of versions on the develop branch?
Maybe we just need to adjust our git workflow a little bit somehow?
How is the GitVersion philosophy here? I assume that the defaults have been chose on purpose, so there
must be a clear idea how the default workflow should look like.

Here is how the incrementation and decrementation happens:

Suppose I am ready to create my first beta release. So I create the branch release/1.0.0

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel':false}} }%%
    gitGraph
       commit
       branch develop
       commit
       commit
       branch release/1.0.0
       checkout release/1.0.0
       commit

Loading

GitVersion gives me the following versions:

• develop: "SemVer": "1.0.0-alpha.2"
• release: "SemVer": "1.0.0-beta.1"

Meanwhile the team continues development and makes new commits on develop.

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel':false}} }%%
    gitGraph
       commit
       branch develop
       commit
       commit
       branch release/1.0.0
       checkout release/1.0.0
       commit
       checkout develop
       commit
       commit

Loading

Now GitVersion incremented the minor version on develop:

• develop: "SemVer": "1.1.0-alpha.2"
• release: "SemVer": "1.0.0-beta.1"
  I am not quite sure what the reasoning behin this is 1.0.0 has not been released yet, not event a beta prerelease version.

Next I decide to make the actual 1.0.0-beta1 release without adding the new changes made on develop.
I initiate the release build which then tags the released commit.

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel':false}} }%%
    gitGraph
       commit
       branch develop
       commit
       commit
       branch release/1.0.0
       checkout release/1.0.0
       commit tag:"1.0.0-beta1"
       checkout develop
       commit
       commit

Loading

GitVersion still generates the same versions, with minor incremented on deveop:

• develop: "SemVer": "1.1.0-alpha.2"
• release: "SemVer": "1.0.0-beta.1"

The team continues development on develop and I after some time we decide to create a new beta
release that includes the changes amde on develop. So I merge the changes from develop into release/1.0.0.

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel':false}} }%%
    gitGraph
       commit
       branch develop
       commit
       commit
       branch release/1.0.0
       checkout release/1.0.0
       commit tag:"1.0.0-beta1"
       checkout develop
       commit
       commit
       commit
       commit
       checkout release/1.0.0
       merge develop

Loading

Now GitVersion decremented the minor version on deveop:

• develop: "SemVer": "1.0.0-alpha.6"
• release: "SemVer": "1.0.0-beta.2"

It stays this way also after I made the release by triggering a relase build on the merge commit which will add the prerelease
tag to it:

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel':false}} }%%
    gitGraph
       commit
       branch develop
       commit
       commit
       branch release/1.0.0
       checkout release/1.0.0
       commit tag:"1.0.0-beta1"
       checkout develop
       commit
       commit
       commit
       commit
       checkout release/1.0.0
       merge develop tag: "1.0.0-beta2"

Loading

• develop: "SemVer": "1.0.0-alpha.6"
• release: "SemVer": "1.0.0-beta.2"

But as soon as deveopment continues with commits on develop that are not yet on release\1.0.0
the cycle repeats.

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel':false}} }%%
    gitGraph
       commit
       branch develop
       commit
       commit
       branch release/1.0.0
       checkout release/1.0.0
       commit tag:"1.0.0-beta1"
       checkout develop
       commit
       commit
       commit
       commit
       checkout release/1.0.0
       merge develop tag: "1.0.0-beta2"
       checkout develop
       commit

Loading

GitVerions again has incremented minor on develop.

• develop: "SemVer": "1.1.0-alpha.1"
• release: "SemVer": "1.0.0-beta.2"

[asbjornu]

Please remove next-version, i.e. delete GitVersion.yml. next-version should only be used sparingly and temporarily, if at all. Try to avoid using it. Use git tag instead. How does removing GitVersion.yml affect your use case?

[bitbonk]

Without a GitVersion.yml it looks like shown below. Basically it just starts with 0.1.0 on develop.

I am willing to adjust my workflow to how GitVersion "thinks" it should be done.
How would I handle prereleases, and have a CI package feed for the develop branch and update the CHANGELOG.md on all branches?
What is the intended "default" GitVersion workflow?

The versions without a GitVersion.yml:

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel':false}} }%%
    gitGraph
       commit
       branch develop
       commit
       commit
       branch release/1.0.0
       checkout release/1.0.0
       commit

Loading

• develop: "SemVer": "0.1.0-alpha.2" (with Gitversion.yml it was "SemVer": "1.0.0-alpha.2")
• release: "SemVer": "1.0.0-beta.1"

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel':false}} }%%
    gitGraph
       commit
       branch develop
       commit
       commit
       branch release/1.0.0
       checkout release/1.0.0
       commit
       checkout develop
       commit
       commit

Loading

• develop: "SemVer": "1.1.0-alpha.2"
• release: "SemVer": "1.0.0-beta.1"

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel':false}} }%%
    gitGraph
       commit
       branch develop
       commit
       commit
       branch release/1.0.0
       checkout release/1.0.0
       commit tag:"1.0.0-beta1"
       checkout develop
       commit
       commit

Loading

• develop: "SemVer": "1.1.0-alpha.2"
• release: "SemVer": "1.0.0-beta.1"

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel':false}} }%%
    gitGraph
       commit
       branch develop
       commit
       commit
       branch release/1.0.0
       checkout release/1.0.0
       commit tag:"1.0.0-beta1"
       checkout develop
       commit
       commit
       commit
       commit
       checkout release/1.0.0
       merge develop

Loading

• develop: "SemVer": "0.1.0-alpha.6" (with GitVersion.yml it was "SemVer": "1.0.0-alpha.6")
• release: "SemVer": "1.0.0-beta.2"

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel':false}} }%%
    gitGraph
       commit
       branch develop
       commit
       commit
       branch release/1.0.0
       checkout release/1.0.0
       commit tag:"1.0.0-beta1"
       checkout develop
       commit
       commit
       commit
       commit
       checkout release/1.0.0
       merge develop tag: "1.0.0-beta2"

Loading

• develop: "SemVer": "0.1.0-alpha.6" (with GitVersion.yml it was "SemVer": "1.0.0-alpha.6")
• release: "SemVer": "1.0.0-beta.2"

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel':false}} }%%
    gitGraph
       commit
       branch develop
       commit
       commit
       branch release/1.0.0
       checkout release/1.0.0
       commit tag:"1.0.0-beta1"
       checkout develop
       commit
       commit
       commit
       commit
       checkout release/1.0.0
       merge develop tag: "1.0.0-beta2"
       checkout develop
       commit

Loading

• develop: "SemVer": "1.1.0-alpha.1"
• release: "SemVer": "1.0.0-beta.2"

[bitbonk]

@asbjornu As requested here, I have created a demonstrating test in this PR #3191. The test does exactly what I described here.

[HHobeck]

I have taken a look into your ReducedReleaseWorkflowDemo scenario. Really nice how you have documented this. ;)

I'm not sure what your releasing and branching strategy is exactly but I can tell you it looks like you are following the git flow workflow. Or I'm wrong? Please see the sequence diagram here.

Anyway I would like to come back to your test scenario and answer your question:

fails! actual: "1.1.0-alpha.2"
We still have not finally released 1.0.0 yet, only even a beta, so why increment to 1.1.0?
Even tough this surprising, it might actually be OK,
at least the version is incremented, which is needed for the CI nuget feed

The different between the alpha and beta release is documented here. That means at this point you are finalizing your beta release someone else can work already on a future release at the same time. What I'm saying is it doesn't matter if you have already released the version 1.0.0 on production or not at this point you know already what the targeting version would be in the development branch (the next version after 1.0.0). Think about it what happened if you role out a alpha release on a test environment to make a demonstration of your new feature.

fails! actual "1.0.0-alpha.3
This is now really a problem. Why did it decrement the minor version?
All subsequent changes on develop will now a lower version that previously
and the nuget packages end up on the CI feed with a lower version
so users of that feed would need to downgrade to get a newer version.

I agree with you this is in my opinion a bug. I think it is already fixed in this PullRequest #3190. For clarification my expectation would be in that case that on the develop branch the version 1.1.0-alpha.0 will be generated. Is it also what do you anticipate?

In addition I want to say that you not often or even never update the changes from develop to the release branch (develop -> release) because you are already feature complete. This is not not permitted in general it is just not common because it changes the alpha version back to zero which might be a little bit confusing for the tester (or if I think about it it might be problematic if you created a nuget package for the alpha version before). Other way around would be more realistic because you are stabilizing the release and want to have the changes in the develop branch as well (release -> develop). If you consider this workflow the version of the alpha and beta version goes always up and never down. If you want to create a new release then you have to create a new release branch for instance 1.1.0 when you are done with the feature phase on the develop branch. Generally release branches are not existing forever and they have to be merged to main and then deleted after they have been released to manufacturing.

[bitbonk]

it looks like you are following the git flow workflow. Or I'm wrong.

Yes, you are correct, we are following the git flow workflow.

For clarification my expectation would be in that case that on the develop branch the version 1.1.0-alpha.0 will be generated. Is it also what do you anticipate?

Yes, I agree.

The different between the alpha and beta release is documented here.

In addition I want to say that you not often or even never update the changes from develop to the release branch (develop -> release) because you are already feature complete.

An this they thing that I didn't understand and the reason why I ran into this problem. For me a beta release did not have to be fully feature complete and I could add new stuff to the release that was done with commits on develop. Basically, I more or less thought of an alpha as being "just less stable" than a beta. 😊

But still, even if the beta was properly feature complete, someone could still have done some bug fixing or minor improvements on develop (maybe because the person initially thought its is not needed in the imminent release) that I now also want to include in the next beta release. I guess that would be a valid, albeit rare, scenario, correct? If so, how if not with a merge, would these changes ideally end up in release\*?

I agree with you this is in my opinion a bug.

The question now is, how could I work around this bug until it is fixed? How could changes made on develop ideally end up in release\* without running into this bug?

[bitbonk]

If am not mistaken, it seems that one possible workaround would be to use cherry picking instead of merging from develop ⇒ release/*.

In FullReleaseGitFlowWithCherryPickWorkaround I exercise a full git flow up unit the final 1.0.0 release and all version seem to be correct.

What do you think?

[HHobeck]

But still, even if the beta was properly feature complete, someone could still have done some bug fixing or minor improvements on develop (maybe because the person initially thought its is not needed in the imminent release) that I now also want to include in the next beta release. I guess that would be a valid, albeit rare, scenario, correct? If so, how if not with a merge, would these changes ideally end up in release*?

I have thought about your scenario the hole day. Actually your scenario is really on of a worst case scenario in a software development process. Hopefully your are not in the role of a product manager because I would suggest you to engage a new one ;). I'm just kidding. Your scenario and the question about it is quite valid. Of course cherry picking would be a possibility. You can merge the changes with rebase and fast-forward or with a squash commit or even manually.

But if we go two steps back and think about the actual business use case you are facing here this is even more complex. What does this mean? Let’s say we have two features feature/A and feature/B. The product manager decide to put this two features in the next release (this will be the version 1.0.0). So you put the features into the develop branch and integrate it until you have proof it in a alpha version. Now you go in the feature complete phase and create a beta version. You doing this by creating just a release/1.0.0 from develop branch (develop -> release), build and deploy a version on a testing environment and give it to your business or tester. Now your product manager comes to you and says: "Pleased release manger I would like to have just the feature/A and a new feature/C in the next release"! Now this is the point where you have already communicate with the business and told the tester that they can expect the feature/A and B in the version 1.0.0. Or you have technical or regulatory constraints who knows!? The point here is that you need to cancel the hole release and skip this number 1.0.0. You are deleting the release branch or even the develop branch and start again integrating the feature/A and feature/C into a new alpha version with the number 1.1.0 (or even 1.2.0 if the version 1.1.0 is burned too) and start the hole process from beginning. You could say but if I delete the release branch the next version will be just the 1.0.0 in the develop branch. Yes you are right but exactly for this use case the next version configuration or bump messages are good for in GitVersion.

In addition I would like to point out here the following: To be on the safe side I would suggest you to create the feature still from the main branch (main -> feature) and preserve it until you have released the features to production (main -> feature -> develop -> release -> main and tagging).

[bitbonk]

@asbjornu and @HHobeck thank you both for your patience and that you took the time dissecting the problem with me in such great detail and helping me to get a clear view on git flow with the GitVersion defaults.

It is now clear to me that there should rarely be the need to get commits from develop into a release/ branch after that release/ has been created because the release/ creation was preceded by a feature freeze on develop and all further commits on develop from now on are already for the next release after the release that is currently being worked on. (That's a key thing that I somehow missed for quite a while.)

Also all commits that are done to finish up the release and to make beta releases are done on release/ only (either directly or through a PR) without going through develop. Those commits are only merged back into develop when the final release is made.

[asbjornu]

So happy you figured it out, @bitbonk! More than happy to help.

[HHobeck]

Also all commits that are done to finish up the release and to make beta releases are done on release/ only (either directly or through a PR) without going through develop. Those commits are only merged back into develop when the final release is made.

Actually I would not fully agree with this statement. The problematic thing is the merge from develop to release (see discussion before) not the other direction. If you want you can always merge from release to develop. Think about it: You are fixing bugs on the release branch and want to have this bugs also fixed on the next alpha version (the branch of the successor release where the development happens). The same like you would fix bug on main and merge it back e.g. to the develop branch. Of course to have a cleaner branch history it would be better to merge only from feature branch (feature -> release; feature -> develop) or hotfix branch (hotfix -> master; hotfix -> develop; hotfix -> release). But at the end from the source code perspective this has the same effect. At this moment GitVersion has some problems with the first variant. But I think this is still a deficit which should be fixed.

Please notice my comment before as well:

[...] Just wondering why you are not creating a feature branch from the main or release branch and merge it two times in release and develop branch (main or release -> feature -> release and develop)? [...]

It's a pleasure for me to help you.

[bitbonk]

You are fixing bugs on the release branch and want to have this bugs also fixed on the next alpha version

Ah yes, that's of course a valid and important scenario.

Of course to have a cleaner branch history it would be better to merge only from feature branch (feature -> release; feature -> develop)

Yes, that's how I would prefer to do it, at least for the common situation that I know beforehand that I want the fix in the next alpha too.

At this moment GitVersion has some problems with the first variant.

OK, is there an issue I can track to understand the problem and see when it's fixed?

[HHobeck]

If you like you can help me finishing the PR. There is a lot of work done but also there are a lot of things todo. IMO your issue is already solved there. You can play around in your test scenario and double check it if I'm right with it.

Anyway here are the things you can help with:
#3190 (comment)

[HHobeck]

The question now is, how could I work around this bug until it is fixed? How could changes made on develop ideally end up in release* without running into this bug?

I'm just surprised that you would like to build a release candidate with version 1.1.0-alpha.0. Because this version is equivalent to the version 1.0.0-beta.1 at the release branch. My suggestion is not creating the version from develop branch but from release branch. The source code is the same right?

If that is not true then you are leaving the git flow workflow and doing your own workflow. Please notice every version or phase has a meaning and reflects an expectation or constraint which can be confusing when you are customizing it. As a workaround you can increase the next version number in configuration and set it explicit to 1.1.0.

[bitbonk]

I'm just surprised that you would like to build a release candidate with version 1.1.0-alpha.0.

I don't want to have a release candidate 1.1.0-alpha.0. I don't know why you assume that, maybe I made a mistake in the test somewhere?

Alpha versions are just "nightly" CI builds that can be used for internal testing or debugging. Those are just internal builds (with a short retention time) that usually don't end up at the customer.
Basically, the main requirement for those alpha builds is that the version always increments (when there are new changes) and that it conveys how it relates to beta and full releases, e.g.: Is it something newer than what was already (pre)released or something older?

If I have to add some commits from develop into release/*, ideally the version of develop does not change at all, because develop did not change and we have neither made a full release nor a new beta release yet. But what it really should never do is decrement.

[asbjornu]

The decrement may be caused by what's described in #3041.

[HHobeck]

In FullReleaseGitFlowWithCherryPickWorkaround I exercise a full git flow up unit the final 1.0.0 release and all version seem to be correct.

What do you think?

Okay that's vanilla cherry picking what you are doing... I think until your version in develop is not so far away from the version in release branch this might be working. But I wouldn't recommend this process (see explanation of the last post). Just wondering why you are not creating a feature branch from the main or release branch and merge it two times in release and develop branch (main or release -> feature -> release and develop)? You should know cherry picking is very error-prone.

[HHobeck]

I have used your test and adapted it slightly. Please take a look to the following file in my PR here: src/GitVersion.Core.Tests/IntegrationTests/PreventDecrementationOfVersionsOnTheDevelopBranch.cs

[bitbonk]

I have used your test and adapted it slightly. Please take a look to the following file in my PR here: src/GitVersion.Core.Tests/IntegrationTests/PreventDecrementationOfVersionsOnTheDevelopBranch.cs

I have made some slight change suggestions in that PR in that file because I assumed those where just copy&paste errors - it still passes.

OK, so the main thing this new test is telling me, that my problem (decrementation of versions on develop) would be fixed in your branch, correct?

Shouldn't this test also do an actual final release into main?

Additionally I learned about the flag track-merge-target.
Is this flag relevant for my scenario? Do I need to set it? What is its default value for the various branches in a default (empty) configuration?

[HHobeck]

I have made some slight change suggestions in that PR in that file because I assumed those where just copy&paste errors - it still passes.

Okay thank you I take a look later and integrate it into the PR.

OK, so the main thing this new test is telling me, that my problem (decrementation of versions on develop) would be fixed in your branch, correct?

Yep that is correct. Should be solved in this version I'm working on.

Shouldn't this test also do an actual final release into main?

I can integrate this aspect as well.

Additionally I learned about the flag track-merge-target.
Is this flag relevant for my scenario? Do I need to set it? What is its default value for the various branches in a default (empty) configuration?

Actually the track-merge-target is without function in the current version. I try to give it a new life. But the question is what is it good for? ;) I have identified a use case but it's not or maybe it is the origin intention of this feature. It was just for debugging purpose it has nothing to do with your problem.

[HHobeck]

Okay please take a look into this integration test and tell me if you are agree.

[HHobeck]

If you do not want to increase the minor version of the develop branch have you tried to change the configuration setting and set the increment property to None?

branches:
  develop:
    mode: ContinuousDeployment
    tag: alpha
    increment: None
    track-merge-target: true
    regex: ^dev(elop)?(ment)?$
    source-branches: []
    tracks-release-branches: true
    pre-release-weight: 0