The ContinuousDelivery mode on the main branch

[dry-lenses]

Hello! First of all, thanks for the tool that makes version management easier. We're using GitVersion since couple of years and are now in the process of trying to switch to GitVersion 6. We are following standard GitFlow and were using mostly default configuration.

We are trying to understand the motivation behind changing the ContinuousDelivery mode (which is the default for the GitFlow workflow) to contain pre-release labels instead of metadata. On one hand of course this is good, because these versions are now distinguishable using SemVer rules, when before they were not (because metadata is not taken into account when comparing versions). However GitFlow also includes develop and release branches which produce alpha and beta builds, and unfortunately: 1.0.0-1 < 1.0.0-alpha.1 < 1.0.0-beta.1. Meaning there might be versions coming from the main branch floating around (at least internally), which will be "older/lower" than alpha and beta versions using the SemVer rules of comparison.

The example in the mode description says:

1.1.0-3
1.1.0-2 (tag: 1.1.0-2) <-- This is the version which has been deployed on testing
1.1.0-1
1.1.0-0

was the tag in the example meant to be 1.1.0, without the pre-release label?

In general, our teams were fine with releasing builds with numerical metadata like 1.0.0+4. At the moment we are thinking that it would be best for us to try and replicate the old ContinuousDelivery version format, and we found this in the BREAKING_CHANGES.md file:

In the GitHub and the Git Flow workflows the label property is by default set to an empty string on the main branch. This yields to a pre-release version on main with an empty tag. Instead of for instance 1.0.1+46 GitVersion generates the full semantic version 1.0.1-46 instead. This behavior can be changed to generate only stable versions (no pre-release version) with setting the label to null (Please keep in mind that the label property on root needs to be set to null as well, otherwise the fallback applies). This change is caused by issue #2347.

however we tried setting this:

label: null
branches:
  main:
    mode: ManualDeployment
    label: null

but we still got the pre-release label in the generated version: 0.4.1-1+45. Are we misunderstanding the entry in the breaking changes file? Thanks in advance!

[HHobeck]

Hello! First of all, thanks for the tool that makes version management easier. We're using GitVersion since couple of years and are now in the process of trying to switch to GitVersion 6. We are following standard GitFlow and were using mostly default configuration.

Oh thank you very much. It is good to hear a positive feedback. I'm glad that you like it. :)

We are trying to understand the motivation behind changing the ContinuousDelivery mode (which is the default for the GitFlow workflow) to contain pre-release labels instead of metadata. On one hand of course this is good, because these versions are now distinguishable using SemVer rules, when before they were not (because metadata is not taken into account when comparing versions).

I think the motivation was to align with the semantic version specification. Like you mentioned to use the metadata section to count the commits would be wrong. In a continuous delivery scenario you want to have a semantic version number which is increasing automatically without tagging. This is also related to your other question related to the examples: The tagging of the commit has in this aspect no effect on the counting mechanism. The example should illustrate, that it doesn't matter if you tag it or not, the next semantic version number will be the same result. That's the use case of using ContinuousDelivery compared to e.g. the ManualDeployment mode where you need to create a tag to signal a deployment or package creation. Makes sense, right?

However GitFlow also includes develop and release branches which produce alpha and beta builds, and unfortunately: 1.0.0-1 < 1.0.0-alpha.1 < 1.0.0-beta.1. Meaning there might be versions coming from the main branch floating around (at least internally), which will be "older/lower" than alpha and beta versions using the SemVer rules of comparison.

Yes, that is also something I have noticed and in my opinion it is a deficit in the design of the semantic version specification. However, because we cannot change it I would suggest either to specify the label to zeta (or better zzz ;)) on main or use the continuous deployment mode (@asbjornu should we change it in the workflow template?). On the GitFlow Examples following is written:

The continuous delivery mode has been used for the main and the support branch in this examples (specified as a fallback on the root configuration layer) to illustrate how the version increments are applied. In production context the continuous deployment mode might be a better option when e.g. the release process is automated or the commits are tagged by the pipeline automatically.

Last but not least I want to point out that on the github flow and git flow workflow all versions are pre-release versions until you have released it to manufacturing (RTM) by creating a dedicated tag.

The example in the mode description says:

1.1.0-3
1.1.0-2 (tag: 1.1.0-2) <-- This is the version which has been deployed on testing
1.1.0-1
1.1.0-0
was the tag in the example meant to be 1.1.0, without the pre-release label?

No that's correct. Please see explanation above.

In general, our teams were fine with releasing builds with numerical metadata like 1.0.0+4. At the moment we are thinking that it would be best for us to try and replicate the old ContinuousDelivery version format, and we found this in the BREAKING_CHANGES.md file:

In the GitHub and the Git Flow workflows the label property is by default set to an empty string on the main branch. This yields to a pre-release version on main with an empty tag. Instead of for instance 1.0.1+46 GitVersion generates the full semantic version 1.0.1-46 instead. This behavior can be changed to generate only stable versions (no pre-release version) with setting the label to null (Please keep in mind that the label property on root needs to be set to null as well, otherwise the fallback applies). This change is caused by issue #2347.

At the point in time this sentence was true. Mean while the behavior has changed and the null means you are allowing all tags and labels to be recognized on the branch by gitversion (see ComparingTheBehaviorOfDifferentDeploymentModes.cs to get an idea). Every version is a pre-release version until you tag it explicit.

however we tried setting this:

label: null
branches:
main:
mode: ManualDeployment
label: null
but we still got the pre-release label in the generated version: 0.4.1-1+45. Are we misunderstanding the entry in the breaking changes file?

The null expression in JSON and YAML is treated differently (empty string would be label: '' and null label:). Please try this:

label:
branches:
  main:
    mode: ManualDeployment
    label:

Happy Branching!

[asbjornu]

With an incrementet template version, I think I prefer option 1. You?

[dry-lenses]

Thanks for all the answers! This all makes sense, I wanted to know whether we understand it correctly. FWIW, we decided to try and go with label: rc (for release candidate), as it describes quite well what such build from main is and is "far down" enough alphabetically.

Also thanks for the tip about using label: instead of label: null, however this still produced a version that has both a pre-release label and build metadata. I see this in the output:

"PreReleaseLabel": "",
"PreReleaseLabelWithDash": "",
"PreReleaseNumber": 1,
"PreReleaseTag": "1",
"PreReleaseTagWithDash": "-1",

wondering why there is both PreReleaseLabel and PreReleaseTag, I thought that tag got renamed to label in this context?

[HHobeck]

If you have a pre-release version of lets say 1.0.0-rc.5+3 the PreReleaseLabel is rc, the PreReleaseNumber is 5 and the PreReleaseTag is rc.5.

[HHobeck]

With an incrementet template version, I think I prefer option 1. You?

Changing to ContinuousDeployment is fine with me as well.

[asbjornu]

Hmyea, the existence of both PreReleaseTag and PreReleaseLabel is indeed confusing. But they are not the same thing, and are both both historical baggage from before tag was renamed to label in #3314. From the documentation:

Property	Description
PreReleaseTag	The pre-release tag is the pre-release label suffixed by the PreReleaseNumber.
PreReleaseLabel	The pre-release label.

With the following example:

{
    "PreReleaseTag": "beta.99",
    "PreReleaseLabel": "beta",
}

In this context, I'd say PreReleaseTag (the vlue beta.99) is what actually represents the "pre release label" and the current PreReleaseLabel is more like a "pre release label name", "pre release label prefix" or something similar. This seems like an omission from both the discussion in #1054 and the PR #3314.

There's not much we can do about this in v6 as it would be a breaking change, but we can consider changing this in v7.