nbgv install creates version.json with potentially incompatible schema reference

[daniel-svard]

When using nbgv install, the URL for the $schema field in the generated version.json is hardcoded to reference the version.schema.json in the master branch (which seems to be redirected to the main branch). This can be confusing as it may guide the user to edit version.json in a manner that is incompatible with the installed version of nbgv, if the schema has been changed since the release was made.

I got bitten by this using the latest (3.5.119) version and trying to use the release.tagName setting. It took me a while to figure out that the feature is yet to be released, however the IDE happily let me use it since it is in the schema. I got confused when running nbgv prepare-release would remove the field in the updated version.json files. It would have been nice with a validation error instead of just ignoring the unknown field.

I suppose it can be a bit tricky to implement, but the generated version.json should preferably reference the correct version of the schema as well.

[AArnott]

I'm sorry for your bad experience here.

I believe newer nbgv tool versions will produce the $schema URI with /main/ as the branch name instead of /master/.

I do understand the issue and frustration with the schema not matching the version of the tool you are using. I don't know how to fix it without creating a worse problem though. We could certainly create the schema URI in your version.json file to point to the exact commit (or perhaps the tag) that matches the nbgv tool used to install it. However I don't think anyone will ever update it. And most NB.GV users don't use the nbgv tool at all, so the goal there wouldn't be to match the tool necessarily, but rather to match the version of the nerdbank.gitversioning nuget or nerdbank-gitversioning npm package in use in the repo.

I don't think any user I've met would ever think to update the URI to get a newer schema. But they do periodically update the package/tool they use to the latest version. If I had to choose between the risk of occasionally having the schema be too new vs. be chronically too old, I think the first option is the lesser of two evils.

I suppose though, that we could at least reduce the pain by maintaining some 'shipped' branch in the repo and have the schema URI point at that. At least then, folks won't see unreleased schema, which won't be good for anyone. They still might see schema newer than their tool, but at least then they'd have a mitigation of updating the tool.

Thoughts?

[KalleOlaviNiemitalo]

I don't think any user I've met would ever think to update the URI to get a newer schema.

I've been updating it.

[AArnott]

What needed updating, @KalleOlaviNiemitalo? Did you use a URL that was version specific instead of main or master?

[KalleOlaviNiemitalo]

Yes, I put the commit ID in so that it cannot break if you ever move the schema to a different directory. Originally like this

"$schema": "https://raw.githubusercontent.com/AArnott/Nerdbank.GitVersioning/9fff1a3c6c5e93689030522a1658f741cbdc0876/src/NerdBank.GitVersioning/version.schema.json"

but more recently, I've been using tags

"$schema": "https://github.com/dotnet/Nerdbank.GitVersioning/raw/v3.4.240/src/NerdBank.GitVersioning/version.schema.json"

[AArnott]

A prudent step, but ya... I'll never move the file as that would break virtually everyone (except you). :)