Stamp your assemblies and NuGet packages with a version from a single, simple version.json file and include git commit IDs for internal builds.
I'm not seeing an easy built in way to tell
nbgv cloud to use the InformationalVersion for the build title/name. Would this be a reasonable thing to PR? Right now the workaround I'm trying is to manually do Write-Host to overwrite the ##vso variable after I invoke nbgv cloud, but it's difficult to get working and I have to scatter it across several YAML files. This is for VSTS (Azure Pipelines).
I'm using path filters (
However, if I add a new project with same settings, its initial height is calculated at what I assume is the height from very first commit with NB. For example, first commit of brand new project might result in version 1.0.84-####. I would have expected that the height would be calculated based on the path filter (subtree only). In other words, since the subtree and version.json file in question has only existed in the repo for exact one commit, the version should be 1.0.1-####.
Am I missing something?
["."]) to manage versions on a number of projects in a mono repo. In this case the development branch is the "release" branch and feature branches are pre-release. Existing projects (a number initially created at the same time) versions seem to work as expected. A merge back into development branch creates a release version. I increment the version for new work after that (e.g. 1.1) and the height is calculated for that project based on height since last merge.However, if I add a new project with same settings, its initial height is calculated at what I assume is the height from very first commit with NB. For example, first commit of brand new project might result in version 1.0.84-####. I would have expected that the height would be calculated based on the path filter (subtree only). In other words, since the subtree and version.json file in question has only existed in the repo for exact one commit, the version should be 1.0.1-####.
Am I missing something?
@NigelWhatling When NB.GV computes the version height, it considers the path to the project whose version is being calculated, at each commit going back in history, so long as the
If all you ever had were subdirs with version.json in each one, and never one in a parent dir of a new dir you created, then I think you could expect a version height starting at 0 (or 1, practically speaking).
BTW: You can force a 'reset' using the
version field of the version.json file has not changed. The commit that introduces a path filter may not be the first commit to set the version. If for example you have a root-level version.json file that sets the version to 1.0, and then you add a new version.json file in a subdir, with a path filter, that also sets (or inherits) the 1.0 version, then you haven't changed the version, and the git history traversal will honor the path filter for those commits that define the path filter, and when it encounters a commit without a path filter (or with a different set of filters), it will honor that for those commits.If all you ever had were subdirs with version.json in each one, and never one in a parent dir of a new dir you created, then I think you could expect a version height starting at 0 (or 1, practically speaking).
BTW: You can force a 'reset' using the
versionHeightOffset property, by setting it to a negative value.
@AArnott Hmm. I do have a version.json file in a parent directory with version 1.0. I didn't think that would be an issue because the project level file overrides the version (with same version in this case) and uses the pathFilter. But it sounds like the parent file is causing the problem. Not sure how I get around that by without some nasty git hacking. 🤔
Thanks for the response. 👍
@NigelWhatling Yes, the new project level file overrides it -- when introduced. But in that commit's parent, it wasn't there to override and yet the version is the same so the height continues to grow.
Do you need the parent-level file? If not, you can remove it. Then, after at least one commit with it gone, a new subdir created with a version.json file will have a version height of 1.
Do you need the parent-level file? If not, you can remove it. Then, after at least one commit with it gone, a new subdir created with a version.json file will have a version height of 1.
One reason for this is that versions going backwards is generally a bad thing. So if your existing project in git has version 1.0.500, and you decide you want to add path filters to it and do so by adding a version.json file to that directory, that shouldn't make the height go backwards to 1, right? You'd simply want it to continue at 1.0.501 but increment less frequently going forward.
@AArnott I think my issue was with how I was looking at the pathFilters setting. Setting it as I have filters away changes, but doesn't change the fact that the version files still inherit up (because I have set them to).
I want to keep the parent-level version file because that is where I have common settings for all of the projects (although, admittedly, there aren't a huge number of those). The only thing that is set in the project-level files is the version for that project (and pathFilters).
Anyhoo... After a bit of git hacking, I eventually updated the parent version.json file to version 0.0 and rebased my project branch. This has done the trick. New build spits out as 1.0.1. 👍
I want to keep the parent-level version file because that is where I have common settings for all of the projects (although, admittedly, there aren't a huge number of those). The only thing that is set in the project-level files is the version for that project (and pathFilters).
Anyhoo... After a bit of git hacking, I eventually updated the parent version.json file to version 0.0 and rebased my project branch. This has done the trick. New build spits out as 1.0.1. 👍
hey @AArnott I have a solution wide version.json, but want to have different rules for a sub project (currently fixed as a preview release). What is the best practice for that?
I would like the preview lib to follow the same versions as the other libs in the same repo, but it should just always have the "preview" version prefix, even when build in release mode/non-prevew mode.
Right now I am using
nbgv prepare-release to create releases/bump release versions.
@egilhansen:matrix.org I would normally prescribe multiple version.json files where the sub-level ones use
Will that suit you?
"inherit": true and then set only what they want to override. nbgv prepare-release only updates one version.json file (the one you point it at), so if you have sub-level global.json files that set "version": "1.2-preview" then they will remain in preview even while the root level one drops its -preview suffix.Will that suit you?
@AArnott: maybe. if I add a version.json inside the "preview project" folder, and set inherits to true, what other options should I add the preview projects version.json to have it always apply the
-preview suffix to the verison, even when the parent version.json doesnt have that suffix in its version, i.e. because it has been removed after running nbgv prepare-release.
The preview folder's version.json will need to set the entire version (e.g.
1.2-preview). Are you saying that nbgv prepare-release is removing the -preview suffix even from the subfolder? (hint: you should be running that tool from the directory containing the root file, or specifying the path explicitly).
@AArnott
How to modify the generated version properties using some msbuild target? We are using the Nuget package, and don't have to do much, we just do these steps in our CI pipeline => VS Build => Nuget Push => Publish => Publish Build Artifacts
Do I need to modify the version properties in the pipeline or is it from our c# code somehow?
@nrpatil1993 No C# or pipeline changes should be required. It's an msbuild target, so you could for example add a Directory.Build.targets file to the root of your repo with content like this:
<Project>
<Target Name="TinkerWithVersionProperties" AfterTargets="GetBuildVersion">
<PropertyGroup>
<NuGetPackageVersion>$(NuGetPackageVersion)-abc</NuGetPackageVersion>
</PropertyGroup>
</Target>
</Project>That would effectively forcibly add -abc to the end of every nuget package. Now there are better ways to do that particular thing, but the point is you can take the msbuild properties that nb.gv sets and tailor them to your exact needs.
You can see the full list of properties that nb.gv sets in msbuild here.
@AArnott
Ok. Did the changes. Have added this file in the same folder where the .csproj exist.
<?xml version="1.0" encoding="utf-8"?>
<Project>
<Target Name="TinkerWithVersionProperties" AfterTargets="GetBuildVersionCore"> // or GetBuildVersion
<PropertyGroup Condition="$(NuGetPackageVersion.EndsWith('$(GitCommitIdShort)'))">
<NuGetPackageVersion>$(MajorMinorVersion).$(GitVersionHeight)-pre$([System.DateTime]::UtcNow.ToString(yyyyMMddHHmmss))</NuGetPackageVersion>
</PropertyGroup>
</Target>
<Target Name="AdjustVersion" AfterTargets="GetBuildVersionCore"> // or GetBuildVersion
<PropertyGroup>
<AssemblyInformationalVersion>$(NuGetPackageVersion)</AssemblyInformationalVersion>
</PropertyGroup>
</Target>
</Project>With this change, when I build the code locally, it is adding Product version with the required version. But when I push it and run the CI pipeline, it still goes with the regular version having git-commit Id in it, and it is not getting updated.
Am I doing anything incorrect here?
@nrpatil1993 Did you perhaps forget to dad the new file to git so that the file would appear on the CI machine?
Another way to investigate this is build (on CI) using the
Another way to investigate this is build (on CI) using the
-bl switch to msbuild or dotnet build and collect the resulting msbuild.binlog file as an artifact. Then open that file using the tool at https://msbuildlog.com and see whether your target runs and what (else) happens to those properties that you're setting.
I tried clearing the nuget cache and I saw that this files were locked by some dotnet.exe processess
nerdbank.gitversioning\3.4.244\build\MSBuildCore\LibGit2Sharp.dll
nerdbank.gitversioning\3.4.244\build\MSBuildCore\NerdBank.GitVersioning.dll
nerdbank.gitversioning\3.4.244\build\MSBuildCore\Nerdbank.GitVersioning.Tasks.dll
nerdbank.gitversioning\3.4.244\build\MSBuildCore\Newtonsoft.Json.dll
nerdbank.gitversioning\3.4.244\build\MSBuildCore\Validation.dll
Hello,
Is it a bug that NBGV uses the new version number from an uncommited version.json but ignores changes to the prerelease-tag?
In an uncommited version.json I can change the version number and nbgv get-version will print the new version directly, without commiting. Changes to the prerelease -tag are completely ignored until I commit the changes.
so when a feature branch is merged to main it should increment on minor level
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.