Stamp your assemblies and NuGet packages with a version from a single, simple version.json file and include git commit IDs for internal builds.
The reason is in git the same commit may appear as a member of any branch, and the set of branches covering a commit may change over time. But the version built from a commit should not change over time because the software itself hasn't changed. But we make it easy to bump the version with a change to version.json before or after a merge either manually or with the
nbgv CLI tool.
If you really want versions to come from branch names, another tool (GitVersion) may be a better fit for you.
Hi, trying to switch from GitVersion to Nerdbank.GitVersion. How do I create a config that will tag as 1.2.3-alpha on develop branch, and 1.2.3 on main branch? See develop branch https://github.com/ptr727/PlexCleaner/blob/develop/version.json
Hi @ptr727. I'm not sure what you mean. I'll say though that GitVersion and NB.GV have different philosophies when it comes to branches. With NB.GV, very little changes by the branch. If you have an alpha branch and a stable branch, that's fine, but the way you accomplish that is by having your alpha branch set with a
version.json file that sets the version to 1.2.3-alpha and your stable branch set to 1.2.2 (or whatever you most recent stable version was). When your 1.2.3 development branch becomes stable, you remove the -alpha suffix from the version.json file for that branch. Does that help?
I was hoping there is a way to have a configuration similar to publicReleaseRefSpec that would remove the prerelease tag, similar to how the commit hash is dropped for main branches. Keeping a different json config per branch is difficult (non-standard for mainline branching) as it means auto merge can never happen. If the github actions config allowed specifying different config files that could work, but is also not supported. For nuget builds the postfix hash does not result in a prerelease, only if I also add alpha/prererelease by hand. Problem with GitVersion is mainline mode fails when trying to do a github prerelease, see ptr727/PlexCleaner#16
Thank you for taking the time to explain. I have more questions to better understand your scenario. I'm coming from a place where code is fundamentally deemed either stable or unstable. A commit represents exactly one state of code so that commit is stable or unstable regardless of what branches happen to include that commit. The only merges I've automated are the ones from servicing branches to the mainline/development branches, which ensures that bugs fixed in servicing do not relapse in a subsequent release.
For example, if I have servicing branch
It sounds though like instead, you are merging a less stable branch into a more stable branch, and in doing so in an automated fashion you also want it automatically promoted from unstable to stable. Is that right? How do the version numbers in these two branches evolve around these events? Given your first comment it sounds like a
For example, if I have servicing branch
v1.0 and a main branch where I'm developing 1.1-alpha, then I may want the v1.0 branch to periodically merge into main so that v1.1 will release with all the same fixes that v1.0 had. Nerdbank.GitVersioning works naturally with this because main will have the most recent change to version.json so a merge from v1.0 will not touch version.json, leaving both branches building the version they mean to.It sounds though like instead, you are merging a less stable branch into a more stable branch, and in doing so in an automated fashion you also want it automatically promoted from unstable to stable. Is that right? How do the version numbers in these two branches evolve around these events? Given your first comment it sounds like a
1.2.3-alpha branch merges into a 1.2.3 branch. What becomes of the source branch at that point? Does it remain 1.2.3-alpha or does it advance to 1.2.4? And was the target branch 1.2.3 before and after the merge?
I follow the simplified mainline mode where there are two permanent branches, main and develop. Main is the release version branch, develop is the beta branch. Builds from main are versioned 1.2.3.4, builds from develop are 1.2.3.4-prerelease. Changes are made to develop, tested, then merged to main when ready. Large or time consuming changes are done in a task specific branch, that branch would later merge into develop, and when ready would merge into main. When I create pull requests, I want to auto merge, no manual merging required. That means that version.json in develop would overwrite version.json in main, as the intent is to apply develop to main. That does not work as per your description the different branches must have different content. It is the latter part that I find incompatible with my workflow (and that of commercial organizations where I've worked). A few possible solutions based on my experience dealing with other versioning tools on azure pipelines and github actions: set the version config file name in the github action config, set the tag in the github action config, configure the tag per branch in the config file. Or much less desirable I ignore the semver version and build the desired tag in the pipeline from the raw attributes reported by the version tool.
Thanks for explaining that. It sounds like that should be common knowledge based on your experience and those around you, so I really appreciate your patiently explaining it to me. My experience has certainly been different. It seems leading up to
I wonder if .gitattributes merge strategies would help here. Once
Ultimately, you have control over the version. If you define your own msbuild target with an
develop's merge to main that the team of devs working in develop would have to 'slow down' and not destabilize the branch. The way I and teams around me have done it is work never slows in the primary dev branch, and stabilization happens after branching off, which gives a fine opportunity to change the version.json file. In fact this is so common we have the nbgv prepare-release command which automates branching off for stabilization that automatically trims the -prerelease tag on the servicing branch and advances the unstable version from 1.2.3 to 1.2.4 or whatever the policy is that you set in version.config.I wonder if .gitattributes merge strategies would help here. Once
main and develop have conflicting changes for version.json, your gitattributes file could allow git merge to work without conflicts and just leave the copy in the target branch alone.Ultimately, you have control over the version. If you define your own msbuild target with an
AfterTargets="GetBuildVersion" attribute, you can review and edit any of the many msbuild properties that NB.GV sets. You could consider the active branch name (BuildingRef) property and remove the -prerelease tag from the version when the branch being built is main.
I've also worked in shops where releases are cut from trunk and trunk is unstable, ideally I'd like to see flexibility for various methodologies. I'll review the merge strategies override option, but I'd venture to say that the easiest and flexible change would be to add a config parameter to the github action task that lets me point to a config file of my choosing at build time, vs. the tool always hardcoding the config file name.
The Github Action just sets environment variables, IIRC. Is that really all you want, or are you using the Nerdbank.GitVersioning nuget package to apply version information to build outputs?
If the latter, you actually can use the
Learn more at https://github.com/dotnet/Nerdbank.GitVersioning/blob/master/doc/msbuild.md#build-performance
If the latter, you actually can use the
GitVersionBaseDirectory property (or environment variable) to specify where to look for the version.json file. So you could have two version files, in two different directories, and have a github action in your workflow set the GitVersionBaseDirectory env var based on the branch being built to achieve what you want.Learn more at https://github.com/dotnet/Nerdbank.GitVersioning/blob/master/doc/msbuild.md#build-performance
The
path property is documented as a root below the config file, or do I misunderstand the usage and it could be a config file? I'm not using MSBuild, I'm using the github actions workflow and I'm using dotnet publish, see https://github.com/ptr727/PlexCleaner/blob/develop/.github/workflows/BuildPublishPipeline.yml
Just an update; I converted a NuGet project, and the version is detected as a prerelease with no changes to manually add a prerelease or alpha tag required, so I'm good, I assume NuGet updated the prerelease detection logic from having to hardcode a tag. I do think adding the ability to specify the tag and the config file to use in the github actions step would allow immense flexibility.
@lvond The package includes the git commit id in the version when PublicRelease is false. The version.json file allows you to set the branches that you release from so that the commit id is automatically omitted. But if you're looking for an msbuild property to force it, use
/p:PublicRelease=true.
@omerfarukz By "depends on this library" do you mean your assembly references Nerdbank.GitVersioning.dll, or do you mean you're using NB.GV just for versioning of your project?
It would be very helpful if you included the callstack of your exception to figure out who/where it's thrown.
It would be very helpful if you included the callstack of your exception to figure out who/where it's thrown.
HI @AArnott
Awesome work :-)
Quick Question: We are using PRs to squash and merge into main and would like to increment the minor version on every merge? So instead of incrementing the PATCH version with the git height it would be incrementing the MINOR version. Is that possible in any way? I know I could do it with prepare-release or manually. But there would be too many merge conflicts.
Thanks in advance
Awesome work :-)
Quick Question: We are using PRs to squash and merge into main and would like to increment the minor version on every merge? So instead of incrementing the PATCH version with the git height it would be incrementing the MINOR version. Is that possible in any way? I know I could do it with prepare-release or manually. But there would be too many merge conflicts.
Thanks in advance
There's nothing built-in to do that, @Franklin89. NB.GV does let you move the calculated height around to the build version (4th integer) or to someplace in the
What you could do though is define an msbuild target that runs after
-prerelease tag, but not the minor version.What you could do though is define an msbuild target that runs after
GetBuildVersion. A bunch of msbuild properties are set by that target and you can read them and rearrange them all you want.
Just know that if you do rearrange them, the
nbgv get-commits and nbgv get-version commands will no longer work for you.
This is my version.json:
{
"$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/master/src/NerdBank.GitVersioning/version.schema.json",
"version": "1.0",
"publicReleaseRefSpec": [
"^refs/heads/master$",
"^refs/heads/v\\d+(?:\\.\\d+)?$"
],
"cloudBuild": {
"buildNumber": {
"enabled": true
}
}
}
I'm building the master branch locally and end up with a product version of 1.0.0-beta+<commit id>
@dirvo there is nothing in NB.GV that would add
Did you recently remove the
-beta without your asking for it. The only place in code where beta even appears that I could find in the repo is in the nbgv tool and is used as a default value when creating your version.json file.Did you recently remove the
-beta suffix from your version.json file? Have you committed that change? Nearly any change to version.json must be committed to take effect (note that the commit does not have to be pushed).