How to use CommitsSinceVersionSource as PreReleaseNumber

[rcdailey]

I have the following GitVersion.yml:

mode: ContinuousDelivery
tag-prefix: 'v'
major-version-bump-message: "^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\\([\\w\\s-]*\\))?(!:|:.*\\n\\n((.+\\n)+\\n)?BREAKING CHANGE:\\s.+)"
minor-version-bump-message: "^(feat)(\\([\\w\\s-]*\\))?:"
patch-version-bump-message: "^(build|chore|ci|docs|fix|perf|refactor|revert|style|test)(\\([\\w\\s-]*\\))?:"

branches:
  master:
    tag: dev

For my normal release process, I always want ContinuousDelivery. I always wait to release until I have a chance to test changes on master, and I make several commits before I do a release. I do not use a sophisticated branching strategy. Since I'm the only contributor on my FOSS project, I commit directly to master and make a release directly on master by creating a tag, pushing that tag up, and having my Github Workflow do a release on that tag (and not on master itself).

If I do make a release on master, it's considered an "edge" build and for testing purposes only. For master itself, I suppose it's fair to say it is closer to ContinuousDeployment, because each commit is a release of an "edge" build.

For those master-based builds, I like the end result of the above YAML configuration, except for the PreReleaseNumber value. It remains stuck at 1 (so it looks like -dev.1). I understand why; it is waiting on me to tag that edge build so it can increment to -dev.2. However, I do not want to tag every commit on master just to increment that number. What I really want is for PreReleaseNumber to be the same value as CommitsSinceVersionSource.

Is this possible? Do I need to do a per-branch configuration for tags & master separately to get this kind of behavior? I'm honestly not sure how to set this up. I'm not even sure if tags can be configured like branches in GitVersion.yml. And even if I'm able to set up master as ContinuousDeployment, I only want that to affect the prerelease tag; not the primary version number (the major/minor/patch components should be governed by tags only, and follow ContinuousDelivery semantics).

I hope what I'm asking for makes sense. I tried to give a lot of examples and detail. Let me know if there's more I can provide. Thanks in advance for any help.

[HHobeck]

Hi Robert,

Actually it's a little bit difficult for me to understand what you are trying to achieve. Could you maybe simplify your scenario? Or better create a integration test based on the main branch (because it targets the next 6.x version of GitVersion). Please let me know if you are not familiar with integration tests.

Thank you.

[rcdailey]

I finally got around to reading your replies.

What would be your expectation if not sequential. Exponential!?

This comes across as sarcastic to me. Of course I have no expectation for it to be exponential; that makes absolutely no sense. I'm talking about conditional behavior. For example, will the number start back over at 1 after a tag? Or does it do something like continue incrementing after that? The question might seem obvious to you, who clearly knows the ins and outs of GitVersion, but outside of my due diligence in reading what documentation I can find, I have to ask the obvious questions to make sure I get a factual answer on the record. I hate making assumptions when I can avoid it.

That means you doing the following steps for a feature release:

I don't need all of these steps for my open source project. I do all my work on master. I do not use release, hotfix, or develop branches. That's why, as hopefully my test code communicates, I need prerelease behavior between tags. I think the fact that all of these versioning modes are being completely redefined on v6 is going to further add to confusion. The distinction between the modes hasn't always been very clear to me to begin with.

The bump message feature like it is implemented in the actual version of git-version is there to bump the increment to a higher value for the calculation of the next version. If lets say the base version is 1.0.0 then the following matrix applies

I wasn't overthinking this. According to the docs, increment for master defaults to Patch anyway, so none of those rules matter to me. I actually am only focused on what changes my commit is introducing (and ultimately my release, which isn't final until I tag). This is why I use semantic versioning to tell GitVersion how to bump version numbers.

Your response got me thinking a bit more and I realized my test assertion was wrong. It won't increment the patch to .1 because I haven't tagged yet, and it's correctly ignoring the patch increment since I already have a minor version increment from a previous commit. In other words, it won't go to 1.1.1 because the last tag is 1.0.0, and 1.1.0 takes precedence since MINOR > PATCH. I hope that makes sense (it does in my head at least!).

The correct (and passing!) test is:

f.MakeATaggedCommit("v1.0.0");

f.MakeACommit("fix: Fix a bug");
f.AssertFullSemver("1.0.1-dev.1", config);

f.MakeACommit("feat: New Feature 1");
f.AssertFullSemver("1.1.0-dev.2", config);

f.MakeACommit("feat: New Feature 2");
f.AssertFullSemver("1.1.0-dev.3", config);

f.MakeACommit("fix: Fix 2");
f.AssertFullSemver("1.1.0-dev.4", config);

f.MakeACommit("fix: Fix 3");
f.AssertFullSemver("1.1.0-dev.5", config);

f.MakeATaggedCommit("v1.1.0");
f.AssertFullSemver("1.1.0", config);

f.MakeACommit("fix: Fix 4");
f.AssertFullSemver("1.1.1-dev.1", config);

f.MakeACommit("feat: New Feature 3");
f.AssertFullSemver("1.2.0-dev.2", config);

At the end I would like to tell you that maybe the mainline or trunk-based workflow is something you have in mind because it requires no tagging at all (but comes with performance impacts). We are going to remove the Mainline mode in 6.x and implement it as a separate version strategy. But this is another story.

You're right, I'm definitely using mainline (in the abstract sense; I cannot speak to what the actual mainline versioning mode is, since even after reading the docs multiple times, I still don't understand it). However, I don't know if we need a true mainline mode. In my mind, mainline is just GithubFlow, or GitFlow without branches. Basically, if the effect of doing all work on master in any of the other modes gets the end result of my test above, then to me, that's "mainline enough".

In closing, I'll say that I'm still surprised about ContinuousDeployment mode solving this problem. Based on the docs, it indicates that continuous deployment is for when every commit is shipped. To me, that means that my test should actually fail, because something like this:

f.MakeACommit("feat: New Feature 1");
f.AssertFullSemver("1.1.0-dev.2", config);

f.MakeACommit("feat: New Feature 2");
f.AssertFullSemver("1.1.0-dev.3", config);

Is how continuous delivery works. In other words, we don't endlessly increment the version. Because we have to tell GitVersion when it has shipped (via a tag). So it will "consolidate" the patch/minor/major version increments until then.

Again, based on the docs, it seems that continuous deployment should behave like this:

f.MakeACommit("feat: New Feature 1");
f.AssertFullSemver("1.1.0-dev.2", config);

f.MakeACommit("feat: New Feature 2");
f.AssertFullSemver("1.2.0-dev.3", config);

Because each commit is "shipped" (I translate this to mean, that each commit is treated as if it were tagged).

Apparently my understanding is wrong, because the (former) test is passing. So even before we get into the changes that v6 introduces, which will further my confusion, I can't even explain the current behavior. I was hoping you could help clear up my confusion with the continuous deployment behavior.

Thank you for all the help so far. You've been very patient with me and I have enjoyed your long, detailed responses!!

[HHobeck]

Like you said until you are not marking the commit with a dedicacted tag it is not shipped to production. This rule is independent of what mode you are using (except for Mainline). Like I sayed in the current version continuous deployment behaves like continues delivery. We are addressing this deficit with the new ContinuousDeployment logic in future (this logic I have explained in one of my last post) and also changing the documentation.

This comes across as sarcastic to me. Of course I have no expectation for it to be exponential; that makes absolutely no sense. I'm talking about conditional behavior. For example, will the number start back over at 1 after a tag? Or does it do something like continue incrementing after that? The question might seem obvious to you, who clearly knows the ins and outs of GitVersion, but outside of my due diligence in reading what documentation I can find, I have to ask the obvious questions to make sure I get a factual answer on the record. I hate making assumptions when I can avoid it.

We have put so much effort to document the behavior and visualized all common scenarious in sequence diagrams. Please don't tell me this information is an inside. Also if you not mind use the integration test and find out what the behaviour is by yourself.

Finally I want to focus on the origin question: How to use CommitsSinceVersionSource as PreReleaseNumber?

This question is I think answered. If you have other question please provide additional Q/A requests. Thank you.

[HHobeck]

I have created a green test to show you the different of ContinuousDelivery compared to ContinuousDeployment in the version 6.0.0-beta.4:

[Test]
public void JustATest()
{
    var continuousDelivery = GitFlowConfigurationBuilder.New
        .WithBranch(ConfigurationConstants.MainBranchKey, b => b
            .WithLabel("dev").WithVersioningMode(VersioningMode.ContinuousDelivery))
        .Build();
    var continuousDeployment = GitFlowConfigurationBuilder.New
        .WithBranch(ConfigurationConstants.MainBranchKey, b => b
            .WithLabel("dev").WithVersioningMode(VersioningMode.ContinuousDeployment))
        .Build();

    using EmptyRepositoryFixture fixture = new("main");

    fixture.MakeATaggedCommit("v1.0.0");

    fixture.AssertFullSemver("1.0.0", continuousDelivery);
    fixture.AssertFullSemver("1.0.0", continuousDeployment);

    fixture.MakeACommit();

    fixture.AssertFullSemver("1.0.1-dev.1+1", continuousDelivery);
    fixture.AssertFullSemver("1.0.1-dev.1", continuousDeployment);

    fixture.MakeACommit();

    fixture.AssertFullSemver("1.0.1-dev.1+2", continuousDelivery);
    fixture.AssertFullSemver("1.0.1-dev.2", continuousDeployment);

    fixture.ApplyTag("1.0.1-dev.2");

    fixture.AssertFullSemver("1.0.1-dev.2", continuousDelivery);
    fixture.AssertFullSemver("1.0.1-dev.2", continuousDeployment);

    fixture.MakeACommit();

    fixture.AssertFullSemver("1.0.1-dev.3+1", continuousDelivery);
    fixture.AssertFullSemver("1.0.1-dev.3", continuousDeployment);

    fixture.MakeACommit();

    fixture.AssertFullSemver("1.0.1-dev.3+2", continuousDelivery);
    fixture.AssertFullSemver("1.0.1-dev.4", continuousDeployment);

    fixture.ApplyTag("1.0.1");

    fixture.AssertFullSemver("1.0.1", continuousDelivery);
    fixture.AssertFullSemver("1.0.1", continuousDeployment);

    fixture.MakeACommit();

    fixture.AssertFullSemver("1.0.2-dev.1+1", continuousDelivery);
    fixture.AssertFullSemver("1.0.2-dev.1", continuousDeployment);
}

[rcdailey]

We have put so much effort to document the behavior and visualized all common scenarious in sequence diagrams. Please don't tell me this information is an inside. Also if you not mind use the integration test and find out what the behaviour is by yourself.

I stated, "...due diligence in reading what documentation I can find", with the intention of hopefully making it clear that I was simply unable to find such documentation, rather than accusing you of a lack of effort or documentation on your part. Also I never stated it is "inside information". I did however state that your deeper knowledge (the "ins and outs") about GitVersion makes these concepts easier to discuss and understand, so I'm at an obvious disadvantage on that front.

Please don't misunderstand. I fully recognize and very much appreciate the work you and the other contributors have done. I also obviously appreciate all the time you've spent here with me discussing this. I feel like it's been extremely beneficial to me.

Also the fact that you continue to write tests to help my understanding is just icing on the cake. Until I start seeing some v6.0 docs, I may go ahead and just do some poking around in the integration tests to try to learn behavior on my own. The test you provided above doesn't seem much different from the current stable version, but just seeing how the prerelease portion of semver is affected probably isn't enough to judge (this is where I'll play around with it more).

Thank you for everything! I very much look forward to trying out v6!

[HHobeck]

No problem. It's a pleasure for me to help you and others. Thank you also for your respectful writing and that you see the ambition we put into this project.