Using prerelease tag in git tag is removed from version numbers

[CasperWSchmidt]

Describe the bug
When tagging a commit, any prerelease tag is trimmed by GitVersion

Expected Behavior

Tagging a commit with fx. 10.2.3-preview.4 should propagate the preview.4 tag all the way to fx. NuGetVersion.

Actual Behavior

The preview.4 tag is trimmed so the version becomes 10.2.3.

Possible Fix

Steps to Reproduce

    [Test]
    public void GivenARepositoryWithSingleCommitIncludingPrelease()
    {
        using var fixture = new EmptyRepositoryFixture();
        const string taggedVersion = "1.2.3-preview.4";
        fixture.Repository.MakeATaggedCommit(taggedVersion);
        fixture.Checkout(taggedVersion);

        fixture.AssertFullSemver(taggedVersion);
    }

Context

Although we're using trunk-based development (or GitHub flow) we don't want to release every commit as a NuGet package for our customers to consume. Therefore we only release commits when tagged with a version. However, we would like to be able to release previews/betas between real releases in order to get new features out there and get some feedback.

Your Environment

Macbook M2 pro
MacOS Ventura 13.5
GitVersion 5.12.0
repo is private so I can't link to it

[HHobeck]

Hi there. Please use the actual pre-released version of git-version (6.0.0-beta.3) and ensure that your issue is not already fixed.

Please see the following integration test:

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

        using var fixture = new EmptyRepositoryFixture("main");

        const string taggedVersion = "1.2.3-preview.4";
        fixture.Repository.MakeATaggedCommit(taggedVersion);
        fixture.Checkout(taggedVersion);

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

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

        using var fixture = new EmptyRepositoryFixture("main");

        const string taggedVersion = "1.2.3-4";
        fixture.Repository.MakeATaggedCommit(taggedVersion);
        fixture.Checkout(taggedVersion);

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

Please notice if you are using a pre-release tag on a branch with differnt label (on main it is an empty label per default) then the pre-release tag will not be considered as a base to increment the pre-release number.

[CasperWSchmidt]

Thank you for the fast reply. I actually checked out the code (using main) and ran the tests locally (including the one mentioned). Your first test does not assert the version I would like (ie. 1.2.3-1 vs. 1.2.3-preview.4) so it is not a useful test for my scenario.

I've tried adding a configuration (with various modes)

[Test]
    public void GivenARepositoryWithSingleCommitIncludingPrelease()
    {
        var configuration = GitHubFlowConfigurationBuilder.New.WithVersioningMode(VersioningMode.Mainline).Build();
        using var fixture = new EmptyRepositoryFixture();
        const string taggedVersion = "1.0.3-preview.4";
        fixture.Repository.MakeATaggedCommit(taggedVersion);
        fixture.Checkout(taggedVersion);

        fixture.AssertFullSemver(taggedVersion, configuration);
    }

Resulting version:
Mainline: 0.0.1
ContinuousDeployment: 1.0.3-1
ContinuousDelivery: 1.0.3-1+1

According to the documentation the flow is as follows:

1. If the current commit is tagged, the tag is used and build metadata (excluding commit count) is added. The other two steps will not execute.

So I would expect GitVersion to respect the tag (all of it) and not start calculating versions.

[HHobeck]

Maybe the documentation is not precise enough. But this behavior is not a new behavior and makes really sense. If you think about it from the release management perspective:

1. Creating a alpha version on develop branch and tag it with 1.0.0-alpha.5 (because you have shipped it as a preview version to alpha tester)
2. Finish the feature development phase and start bug fixing and stabilization phase on the release branch/1.0.0
3. Creating a new version on the release branch will start with one (e.g. 1.0.0-beta.1) and not with six because the number of the previous pre-release tag will be not considered

If you want that the tag 1.2.3-preview.4 to be considered why you are not specifying on the main branch the label property with the value preview?

[CasperWSchmidt]

It might not be a new behaviour, but that doesn't make it either right og wrong :)

I get that it makes sense from the scenario you describe, but your scenario expects GitVersion to calculate the version numbers which is not correct according to the documentation. Reading the documentation it is expected that GitVersion uses the tag as-is. Also, in case of having different prerelease labels for develop and release/ branches it would make sense that the counter can't be reused (making your scenario correct).

Btw. I've tested using preview as label for release/ branches and it seems to work as we would like. I believe I had some issue yesterday where it didn't accept 1.2.3 without adding a label.

[CasperWSchmidt]

@HHobeck Although I've marked your comment as the answer, I would still like to know why GitVersion starts calculating the version instead of just taking the tag as a whole when the documentation states otherwise.

I believe being able to specify the exact version (including preview label) using tags is a useable feature.

[HHobeck]

@HHobeck Although I've marked your comment as the answer, I would still like to know why GitVersion starts calculating the version instead of just taking the tag as a whole when the documentation states otherwise.

I believe being able to specify the exact version (including preview label) using tags is a useable feature.

Actually I'm not understanding your uncertainty about the behavior. In git-version you have more than one possibilities to influence the version number. One way is using tags but that's not the only way e.g. with next-version you can specify a higher version and overrule the other stragies. So we need to determine all base versions using different strategies and take the version with the highest number for calculating the next version number. The only exception I see is when the current commit has been tagged.

[HHobeck]

I believe being able to specify the exact version (including preview label) using tags is a useable feature.

If you want to define a branch with multiple pre-release labels you need to specifiy the label with null value (on branch and root level).

public void EnsurePreReleaseTagLabelWillBeConsideredIfNoLabelIsDefined(long patchNumber)

Edit: I have the impression that you try to use the pre-release number for something which is not meant for. If you want lets say a number which goes always up you can use the commit count as iteration number.

assembly-versioning-scheme: MajorMinorPatchTag
assembly-file-versioning-scheme: MajorMinorPatchTag
assembly-informational-format: '{MajorMinorPatch}+{Sha}'

[CasperWSchmidt]

Perhaps it can clarify things if I explain the flow we would like to use.

We have to support multiple major versions of our product. Each major has an expected lifetime of 2+ years (depending on how often we make breaking changes that warrants a new major release). To reduce cognitive load on developers we have chosen a scheme as follows (I will call it multiple-trunks-based development):

• Main is renamed to release/v1 but is for all intents and purposes main (using trunk-based development)
• All features and hotfixes will be made using branches (ie. feature/ and hotfix/) and merged to main (release/v1) after code-review using pull requests (pretty standard GitHub flow)
• When a breaking change is implemented, a new branch release/v2 is created from release/v1
  • We intent to use next-version property in GitVersion.yml to specify 2.0.0 when the new branch is created to make sure GitVersion will understand
  • New features will now (primarily) be developed on release/v2, but might be ported to release/v1 via either cherry-pick or re-implementation (depending on the breaking changes)
  • Hotfixes will be implemented where needed (either directly on release/v1 if release/v2 is not affected, or on release/v2 with possible back-porting to release/v1)
• We do not want to release all builds to our NuGet feed - only those tagged with a specific version (fx. 1.2.3 or 1.2.3-preview.4). We have a pipeline in Azure DevOps to handle this.

It's entirely possible that using this strategy is complete nonsense, but we have had a lot of discussions internally and this is in our opinion the best way to handle things (we want to avoid GitFlow).

[HHobeck]

In the current version of git-version the mainline mode does not play well with next-version (this two features are not compatible). But again if you specify the label with the value preview on the release branch it should working like you have described it.

[CasperWSchmidt]

We have kept the ContinuousDelivery mode from main for the release branches but set is-mainline to true. I'm not sure if this will be a problem as well?

[HHobeck]

We have kept the ContinuousDelivery mode from main for the release branches but set is-mainline to true. I'm not sure if this will be a problem as well?

No this should be okay.