Hotfix branch merge resulting in pre-release number reset

[CSymes]

Prerequisites

• I have written a descriptive issue title
• I have searched issues to ensure it has not already been reported

GitVersion package

GitVersion.MsBuild

GitVersion version

v6

Operating system

Windows

What are you seeing?

Under some scenarios, merging a hotfix branch back to develop prior to merging into main causes the prerelease number of the commits on develop to regress.

#4501 discussed a very similar issue, however the resolution there was limited to version numbers being sourced from commit messages, whereas we are reliant on conventional commits to determine our numbers in our case.

Some additional notes:

• We are using a mildly modified GitFlow configuration, although the issue occurs even using the default GitFlow config
• In our live system where we have experienced this, the skip backwards was much greater than one (22->5 or thereabouts), likely due to additional feature branches which I have not included in this reproduction, for simplicity.
• Merging in the other order (into main, then into develop) avoids the issue.
  • As does merging into develop from main instead of the hotfix
  • Unfortunately we can't rely on developers remembering to merge with the correct order or source brounches
• If the hotfix release is not tagged, develop is not affected.

Is this behaving as intended? The behaviouir's dependence on order of merges seems to indicate an issue to me, but if there isn't, is there a way to configure our way around the problem?

What is expected?

develop's commits' prerelease numbers should monotonically increase.

Steps to Reproduce

Make a merge from a hotfix branch to develop prior to merging to main and tagging a release using GitFlow.

RepositoryFixture Test

    [Test]
    public static void RunFixtureSimpleMinimal()
    {
        const string developBranch = "develop";
        const string hotfixBranch = "hotfix/hf";

        var configuration = GitFlowConfigurationBuilder.New
            .WithMajorVersionBumpMessage("BREAKING CHANGE")
            .WithMinorVersionBumpMessage("^(feat)")
            .WithPatchVersionBumpMessage("^(build|chore|ci|docs|fix|perf|refactor|revert|style|test)")
            .WithCommitMessageIncrementing(CommitMessageIncrementMode.Enabled)
            .WithBranch("develop", b => b
                .WithLabel("develop")
                .WithRegularExpression("develop")
            )
            .WithBranch("main", b => b
                .WithLabel("")
                .WithRegularExpression("main")
            )
            .WithBranch("hotfix", b => b
                .WithLabel("hotfix")
                .WithRegularExpression("^hotfix?[/-]")
                .WithDeploymentMode(DeploymentMode.ContinuousDelivery)
            )
            .Build();

        using var fixture = new BaseGitFlowRepositoryFixture("1.0.0");
        fixture.NoteVersion(configuration);

        // Feature
        fixture.MakeACommit("feat: f1");
        fixture.NoteVersion(configuration);

        // Release 1.1.0
        fixture.Checkout(MainBranch);
        fixture.MergeNoFF(developBranch);
        fixture.NoteVersion(configuration);
        fixture.ApplyTag("1.1.0");
        fixture.NoteVersion(configuration);

        // Hotfix
        fixture.Checkout(MainBranch);
        fixture.BranchTo(hotfixBranch);
        fixture.MakeACommit("fix: applied hotfix");
        fixture.NoteVersion(configuration);

        // Merge hotfix->develop
        fixture.Checkout(developBranch);
        fixture.MakeACommit("feat: f2");
        fixture.NoteVersion(configuration);
        fixture.MergeNoFF(hotfixBranch);
        fixture.NoteVersion(configuration);
        fixture.MakeACommit("chore: foobar");
        fixture.NoteVersion(configuration);

        // Merge hotfix->main
        fixture.Checkout(MainBranch);
        fixture.MergeNoFF(hotfixBranch);
        fixture.Remove(hotfixBranch);
        fixture.NoteVersion(configuration);
        // tag release
        fixture.ApplyTag("1.1.1");
        fixture.NoteVersion(configuration);

        // Feature 5
        fixture.Checkout(developBranch);
        fixture.NoteVersion(configuration);
        fixture.MakeACommit("feat: f3");
        fixture.NoteVersion(configuration);
    }

Note this is using a variant of the AssertFullSemver method to provide debug graphs without asserting, but these can easily be swapped out for assertions or removed.

    public static GitVersionVariables NoteVersion(this RepositoryFixtureBase fixture, IGitVersionConfiguration? configuration)
    {
        var variables = GetVersion(fixture, configuration);
        fixture.SequenceDiagram.NoteOver(variables.FullSemVer, fixture.Repository.Head.FriendlyName, color: "#D3D3D3");
        return variables;
    }

Output log or link to your CI build (if appropriate).

[HHobeck]

I would like to simplify this scenario for the discussion (If you not mind). If you have the following use case:

then you see that the semantic version decreases from 1.1.0-alpha.2 to 1.1.0-alpha.1 on the develop branch (as expected). The reason for this is that the commits that are part of the new develop branch have changed. The only workaround is to use the ManualDeployment mode IMO.

In the past, GitVersion had many bugs where the semantic versioning was inconsistent. This has been gradually improved so that the major, minor and patch digit remains stable. Now you are complaining about that the pre-release number is inconsistent, which can be seen as a good sign :). Anyway, if you have suggestion how we could make the algorithm better, please let me know (because I have no idea).

Let me know what do you think.

[Test]
public void __Just_A_Test__()
{
    var configuration = GitFlowConfigurationBuilder.New.Build();

    using var fixture = new EmptyRepositoryFixture();
    fixture.MakeATaggedCommit("1.0.0");

    fixture.BranchTo("develop");
    fixture.MakeACommit();
    fixture.BranchTo("hotfix/next");
    fixture.MakeACommit();
    fixture.MakeACommit();

    // ✅ succeeds as expected
    fixture.AssertFullSemver("1.0.1-beta.1+3", configuration);

    fixture.Checkout("develop");
    fixture.MakeACommit();

    // ✅ succeeds as expected
    fixture.AssertFullSemver("1.1.0-alpha.2", configuration);

    fixture.Checkout("hotfix/next");
    fixture.MergeTo("main", removeBranchAfterMerging: true);

    // ✅ succeeds as expected
    fixture.AssertFullSemver("1.0.1-4", configuration);
    fixture.ApplyTag("1.0.1");

    fixture.Checkout("develop");

    // ✅ succeeds as expected
    fixture.AssertFullSemver("1.1.0-alpha.1", configuration);
}

Edit: Maybe just the merge from main to develop is obligatory?

[CSymes]

Thanks for the reply, and apologies for not replying sooner!
Yes, that is a more minimal example, thanks for that.
I am also very grateful for the work the team has made on GitVersion, and like you say, it's great that this is the level of problem that we're talking about rather than issues with the actual version numbers.

I don't have too many good ideas on how to solve this, either, not being super familiar with how the tool works under the hood.
Naively I might suppose that it would make sense to only include commits in the calculation that are older than the commit under test (i.e. existed at the time that the commit was created), but relying on timestamps may not play very nicely with history rewrites, rebases, etc, so that is probably a non-starter.

The other option that I need to investigate is whether we can get away with only incrementing the patch number on the develop branch. This way, when the hotfix is released, the patch is bumped on dev, and it's ok that the prerelease resets because we still have an increased version number, aside from the prerelease counter.
I think this would have issues with actually bumping the number to the correct version when we want to perform a release (especially major bumps), but I'd have to have a poke around.

[HHobeck]

What about this?

Maybe just the merge from main to develop is obligatory?

I mean you have created a hotfix release with at least a new merge commit. This commit(s) needs to be merged back to the develop branch anyway. Is it maybe just a deficit in your release process?

[JTLMarcVoelker]

(Coming from #5077 — thanks @HHobeck for pointing here.)

We hit the same regression, with one detail relevant to the "is this by design?" question: in our case the hotfix is already tagged on main first, and develop still regresses on the (obligatory) main → develop merge-back.

Our flow (concrete):

• hotfix/0.2.1 branches from main at tag 0.2.0, gets the fix commit.
• hotfix/0.2.1 is merged into main; tag 0.2.1 is placed on that merge commit on main (the fix commit itself is untagged).
• main is merged back into develop to keep it in sync (the obligatory merge-back).
• develop was 0.3.0-beta.168; after the merge it becomes 0.3.0-beta.91.

So the order is already "tag on main first, then merge to develop", and it still regresses — the merge pulls the 0.2.1 tag into develop's ancestry, it becomes the VersionSource, and the commits-since count is now measured from 0.2.1 instead of the 0.2.0 baseline.

Why this isn't just cosmetic for us: we publish these as NuGet packages. A regressing pre-release number makes the counter re-walk numbers it already published (beta.91 … beta.168) and re-emit e.g. 0.3.0-beta.150 a second time with different content. NuGet treats an identical version string as the same immutable package → feed collision / ambiguous restores. So a monotonic develop pre-release number is a correctness requirement for us, not aesthetics.

How I think it could behave (concrete proposal):
develop accumulates toward the next minor; its counting anchor is the last minor/major baseline (X.Y.0). A patch/hotfix release tag (X.Y.Z, Z > 0) that gets merged up should not become develop's VersionSource — the anchor should stay on the minor baseline. In our example develop should keep counting from 0.2.0, not jump to 0.2.1. The hotfix commits still land in develop (nothing lost, your point holds); they just don't reset the counter, because a patch tag on an already-counted-from line isn't a new baseline for develop's 0.3.0 line.

On the alternatives you mentioned:

• ManualDeploymentMode works, but it drops the automatic commits-since counter entirely and moves the "monotonic number" burden to CI — a step back from what GitVersion gives us for free.
• We verified ignore.sha for the hotfix tag commit as a workaround (VersionSource falls back to 0.2.0, counter grows monotonically again) — but it needs one manual entry per hotfix. A general "don't anchor develop on patch-level tags" rule (or an option for it) would solve it without per-hotfix maintenance.

Happy to add a RepositoryFixture repro of the main→develop variant if that helps.

[HHobeck]

develop was 0.3.0-beta.168; after the merge it becomes 0.3.0-beta.91.

Can you provide steps to reproduce for this, please? Maybe provide an integration test or just git commands.

[JTLMarcVoelker]

Follow-up: a verified hotfix-from-main reproduction — and a correction to my earlier framing.

My earlier comment blamed the main → develop merge itself; that was imprecise. Reproducing in throwaway repos (GitVersion 6.5.1, workflow: GitFlow/v1), the real trigger is the merge order of the hotfix relative to its tag — exactly what the OP described. The hotfix does branch from main (never develop) in our workflow.

Reproduction (hotfix from main):

git init -b main && git commit --allow-empty -m init && git tag 1.0.0
git checkout -b develop
for i in 1 2 3 4 5; do git commit --allow-empty -m "d$i"; done   # develop -> 1.1.0-beta.5

git checkout -b hotfix/1.0.1 main
git commit --allow-empty -m fix

# merge the hotfix into develop BEFORE it is tagged on main
git checkout develop && git merge --no-ff hotfix/1.0.1          # develop -> 1.1.0-beta.7

# finish the hotfix on main and tag it
git checkout main && git merge --no-ff hotfix/1.0.1 && git tag 1.0.1
git checkout develop                                            # develop -> 1.1.0-beta.6  (was beta.7 -> REGRESSION)

Same base, but adding the tag on main decreased develop's pre-release number (beta.7 -> beta.6). VersionSourceSha flips 1.0.0 -> 1.0.1; the hotfix commit is now both an ancestor of develop and part of the 1.0.1 lineage, so it drops out of the commits-since count.

The safe order is monotonic: tag on main first, then main -> develop (beta.5 -> beta.6). So it is order-dependent, as the OP noted.

Notes:

• Magnitude scales with how many develop-reachable commits fall into the tagged lineage (OP saw 22->5, attributed to feature branches); the single-commit case above drops by 1.
• Why it matters for us: we publish these as NuGet packages, so a decreased pre-release number can re-emit an already-published version with different content (NuGet immutability -> feed collision).
• ManualDeploymentMode avoids it but drops the commit-count counter; ignore on the tag works but needs a per-hotfix entry. A configurable "don't let a merged-up hotfix/patch tag move develop's VersionSource" would fix it while keeping the obligatory merge-back.

Happy to turn this into a RepositoryFixture test if useful.

[HHobeck]

Thank you for providing the Git commands. I think they make the scenario much easier to discuss.

That said, I still think the issue comes down to the branching, merging, and deployment strategy.

Why would you create and publish a NuGet package in the window between:

• merging the hotfix into develop, and
• merging the hotfix into main and creating the release tag?

I want to point out another aspect: The workflow still requires syncing main back into develop. Once that happens, the hotfix commit is already part of the released version, so it is expected that it is no longer counted as a new commit for develop. As I mentioned earlier, from GitVersion's perspective that commit is already part of the release history.

Befor sync:

After sync:

Even if GitVersion were changed to preserve the higher pre-release number in this intermediate state, the version would still have to change once main is merged back into develop. At that point, the hotfix becomes part of the tagged release lineage, so the commit count must be recalculated. In other words, the increment "flip" is not eliminated, it is only delayed until the required synchronization from main to develop.

TL;DR

• Don't merge the hotfix branch directly into develop.
• If you need the fix in develop before the hotfix is released, apply it as a separate commit (e.g. cherry-pick) or use a squash merge.
• After the hotfix has been merged into main and tagged, sync the branches by merging main back into develop.

Edit: The same behavior occurs if you fast-forward the hotfix into main instead of creating a merge commit. The history is cleaner, but the underlying issue remains because it is caused by the tagged hotfix commit becoming part of develop's history.