Nerdbank.gitversioning: Document requirement to commit version.json changes, and add build warning

[colin-young]

I have the following version.json:

{
  "version": "1.0.0",
  "publicReleaseRefSpec": [
    "^refs/heads/net-core$"
  ]
}

The .csproj contains:

    <Version>1.0.14.0</Version>
    <AssemblyVersion>1.0.0</AssemblyVersion>
    <FileVersion>1.0.14.0</FileVersion>

Previously the version was 1.0.0-beta.{height} and I got the expected version set on building. I modified the version.json to the version shown and when I run dotnet build MyProject.csproj //p:PublicRelease=true -c Release I get assemblies in the Release folder with the beta information for the Product version. dotnet pack produce a NuGet package with the beta versioning on it also.

I've run dotnet clean, manually deleted all generated artifacts, etc. and still get the same results. I've also tried running MSBuild with the same results.

nbgv get-version produces:

Version:                      1.0.0.1
AssemblyVersion:              1.0.0.0
AssemblyInformationalVersion: 1.0.0-beta.1+gc94793e392
NuGet package Version:        1.0.0-beta-0001-gc94793e392
NPM package Version:          1.0.0-beta-0001-gc94793e392

Where is it getting that information from?

[AArnott]

Commit your change. Then try building again.

[colin-young]

That would be the change to version.json? In retrospect, that seems obvious... I'll update on Monday after testing.

[AArnott]

Yes. I should probably mention that as a requirement in more of the documentation, since you're hardly the first person to have hit this.

[colin-young]

To be fair, it's not the normal way of using the tool, but I expect a lot of people do what I do and try to figure out if/how it works locally before deploying to their production build server and may not have a testing build server available (yay corporate red-tape!).

[AArnott]

I agree. One of the core tenets of NB.GV is that the build locally on your dev box produces the same result as a production build server. This requirement to commit and try again isn't meant to suggest you need to _push_ your commit to see the change. You can just commit your change locally and build and you should see the change.

As a git history-based versioning system, committed version.json files are core to the functionality of the system. So un-checked in changes to the file can create odd ambiguities. But through docs and perhaps build warnings, I'm sure we can improve the discoverability of this requirement.

[colin-young]

Yup. That's looking better. When you step back and think about how this all works from a build server perspective, of course you need to commit those files otherwise the build server is never going to see the changes. Maybe a warning like version.json has uncommitted changes, using committed version to generate version would be helpful.

In my defense, I'm not a build engineer, I just sometimes play one at work.

Thanks!

[michael-hawker]

Yeah, think we hit this too trying to update version.json to a different format for PRs, super confusing.

Hoping calling nvgv set-version before nbgv cloud will work??? But doesn't appear to... Oh, it just writes back to the file, so back to square one..

[AArnott]

@michael-hawker Why are you trying to get a different version format for PRs? The PublicRelease flag should be false for PRs, leading to a -gSomeCommitId suffix on your builds to let you know they are not from a normal shipping branch.

[michael-hawker]

@AArnott we were trying to setup two feeds, one for our latest builds and then another for PRs. Instead of having 'x.y.z-build.{height}' for the format we use in the latest feed, we wanted 'x.y.z-pullrequest####.{height}' for the pull request feed. That way we could have the pull request number in the package version as well for better identification.

Though we realized too that if we did a local commit to try and fix this it'd probably mess up the source link commit hash. So, for now we've abandoned trying to change the naming scheme.