When does patch version get reset to 0 or 1?

[johnwc]

When using this tool, and creating a release branch using prepare-release the patch number does not get reset back to 0 or 1 in the release branch. How do we get it to reset, so that releases start at v4.3.0 instead of v4.3.1409?

[AArnott]

What you describe isn't the default behavior, because that is discouraged behavior. Doing that would mean you're building the same package version for multiple distinct versions of your source code. That leads to package cache poisoning, where someone who already had v4.3.1 from your main branch in their package cache cannot consume v4.3.1 from your release branch until they realize they have to delete the old 4.3.1 package from their cache so that nuget restore brings down the new one.
And if your CI pushes packages from main to a nuget feed, you simply won't have the option to push 4.3.1 a second time.

So while you can do what you want (by setting versionHeightOffset: -1409 in your version.json file), I strongly discourage it.

And FWIW, I've never heard a customer complain about 4.3.1409 being released instead of 4.3.0 or 4.3.1. A very few developers of the software itself (such as yourself) feel a bit ruffled at first when they discover this behavior, but I encourage you to consider giving up the need to release a .0 version. I haven't in many years... and no user has even mentioned that they noticed.

[johnwc]

We never have the issues that you refer to because our main branch is always labeled as being a prerelease, which includes beta/alpha and the commit id. So, never causes two builds to have the same version. Release branches under releases/ are the only branches that get a stable release stamped on them as well as only version that can make to production.

Also, a lot of people make the claim I never heard of... so it must not be important. I would say that a lot of people don't stand up and voice their opinion or requirements and just fold to what cards they've been handed. Just because we don't hear about things, does not mean they are not important to someone else. A very good scenario for wanting the revision reset to 0 or 1, is the KISS principle. Keep it simple stupid. Our team along with our users want to be able to look at a release version and know quickly if a new version was pushed. Being able to see v4.3.8 move to v4.3.9 or v4.3.10 is much easier to remember, than v4.3.1423 moving to v4.3.1432 (Think about someone looking at the version on Friday as they leave their office, knowing there is a fix being worked on they need. Then coming in Monday to see if the version updated over the weekend.)

[AArnott]

We never have the issues that you refer to because our main branch is always labeled as being a prerelease, which includes beta/alpha and the commit id.

That's good, but it leaves another problem. Per sem-ver rules, 1.2.1409-alpha is newer than 1.2.0, but because you're rewinding the 3rd integer, it may in fact be much older.
To get this right per semver rules, you'd need to move the version height component. You can do this in version.json with something like this:

{ "version": "1.2-alpha.{height}" }

This way, you'll build 1.2-alpha.1409 from main and then 1.2.0 and 1.2.1 from your release branch, which semver will see as newer than your alpha builds.

You make a fine point about the KISS principle. Just keep in mind even if the behavior you're asking for was automatic (that the patch version restarted at 0), you'd still get patch versions that are not necessarily consecutive, because you may merge several changes into your release branch between releases, and NB.GV counts commits for the version height.

If you're going for the full control approach where you definitely want to start at 0 and definitely want consecutive numbering, then you can set the 3rd integer in your version.json explicitly and increment it manually. You'll still get some NB.GV benefits even in that configuration, because assembly version stamps can still include the version height (as the 4th integer) and the git commit ID itself is still burned into certain binary files by default.

[johnwc]

We do that, we set the height after the prerelease like in your example. This was the only way we could get npm to see the next prerelease as an update to a npm package. We originally had it doing the OoB version stamping of v1.0.40-beta, releasing it to our internal npm repo and using it within other packages. But when the next update came out and it was now v1.0.41-beta, npm outdated did not see that the new update was in fact 'wanted'. Once we changed it to v1.0-beta.40, we could simple run npm update and it would update to next prerelease.

As for the consecutive patch versions in release branches. When we need to make a patch to a release, we create a new branch from the release, work on patch, make a PR from patch branch back into release branch using squash merge. Causing all the commits from patch to be in one commit. Then we create a PR from patch branch into main, using standard marge that keeps commit history. Our main branch has all history from beginning of project, allowing to look for specific work or changes if needed.

We would much rather not have to manually set the third digit, or manually apply the versionHeightOffset in the version.json. Can there be a new command line switch for prepare-release that has it set the versionHeightOffset to current height in the release branch?

[AArnott]

Can there be a new command line switch for prepare-release that has it set the versionHeightOffset to current height in the release branch?

I don't see why not. I think the switch should fail if the version height had not already been moved into the prerelease tag as discussed above to avoid inadvertently reusing numbers or violating semver ordering.

Would you care to author that pull request?

[johnwc]

Can you explain the constraint better, how do we test for that situation?

I wouldn't mind authoring the addition.

[AArnott]

Sure. The condition is that {height} must be explicitly placed somewhere in the prerelease tag and that the prerelease tag is being removed (along with the {height} macro) by the prepare-release command in order for that command to automatically add a versionHeightOffset property that brings the PATCH version to 0.

For instance, this version.json would be allowed to use the prepare-release --reset-version-height-to-zero switch, when the "" argument is left empty or would be sorted by semver as newer:

{
   "version": "1.2-beta.{height}"
}

But using that switch would produce an error if the version.json file were just this:

{
   "version": "1.2-beta"
}

Even the first file that would typically allow it, would disallow it if prepare-release were invoked with a new tag that sorts as older than its current one. So given file 1 (with version set to 1.2-beta.{height}) this command would succeed:

nbgv prepare-release rc --reset-version-height-to-zero

rc sorts as newer than beta so semver would recognize the new versions as newer even though version height was reset to 0.
But this command would produce an error:

nbgv prepare-release alpha --reset-version-height-to-zero

because alpha sorts as older than beta and thus new versions would be seen as older.

[johnwc]

Ok, so do the following verifiactions

1. A regex test on the version to make sure the height is after the prerelease tag.
2. If they set a tag in the command line, be sure it sorts after whatever the prerelease tag is set via the version.json.

If both pass, set the versionHeightOffset field on the release branches version.json. If versionHeightOffset already has a value, update it.

[AArnott]

If both pass

and the CLI switch requesting this behavior is present.

A regex test on the version

I suppose, if that's the easiest way to go about it. But I suspect when you get into that code that you'll find a simpler way. For example just the presence of {height} might infer that there's a prerelease tag.

[johnwc]

I suppose, if that's the easiest way to go about it. But I suspect when you get into that code that you'll find a simpler way. For example just the presence of {height} might infer that there's a prerelease tag.

I can just do a simple check that version ends with {height} instead of the regex test.

[johnwc]

@AArnott unrelated to this, but what would cause this? Running nbgv cloud -a outputs that the version is 1.3.1-beta.5... but the build gets set as 1.3.1-beta.0... And the library project that was updated was stamped with 1.3.1-beta.3... We are using the mono repo versioning to only version the project that was changed, just to give some perspective of the setup.

[AArnott]

nbgv doesn't consider msbuild, so the only thing that matters is what directory it considers as the base, which is the working directory by default.
But msbuild defaults to considering the project directory as the input to version calculation. So if that isn't the same as where you run nbgv, that can explain the difference.
Also, an msbuild property exists that tells a project to always use some other directory as the basis for version calculation. So if you're setting that, you may want to try running nbgv from that directory for consistent results.

[johnwc]

But what about the inconsistency of the build label not being what is printed in the task output from nbgv cloud -a?

[AArnott]

Oh that. It's probably that you're setting the build label to something else later in the build. In fact the default behavior of Nerdbank.GitVersioning is to set the cloud build number for every msbuild project's build, which in your case probably doesn't make sense and you should probably turn that off.