WIP - Exploration to expose extended git details to MSBuild

[robmen]

@adamralph I'm opening this PR to see if you are interested in changes like these. It exposes more git information to MSBuild that allows us to use the MinVer concepts in our more complicated build systems like in the WiX Toolset.

If you are interested in these additions, I'll need to clean up the code quite a bit, and I would appreciate any feedback you have at this time so that I can factor it to your liking.

If you are NOT interested in the complexity added by this PR, that's totally cool. I really appreciate the ideas you put forward in MinVer. It changed (simplified!) the way I think about versioning using git.

There are two "features" in here. I'm sorry. I should have separated them into separate commits, and I will do that if this PR interests you.

1. Expose the various pieces of the git version to MSBuild. This allows us to do various string concatenations and (in some cases) math operations in MSBuild .targets files to address the various versions in our build system.

2. Adds a boolean to include the default pre-release labels even when the tag has pre-release information. We use default pre-release labels like dev on all dev builds. After releasing an rc-1 we like the dev builds to still have the dev label, like 1.0.0-rc.1.dev.1. This is mostly a vanity feature, but it turned out to be pretty straightforward to wire in so I took a shot at it. If you like this feature, I'd also add it to the minver.exe to maintain consistency.

Let me know if you are interested. Again, I know the code needs to be cleaned up but I didn't want to do too much if it turned out this added more complexity than you want in MinVer (that's why I jokingly called the new MSBuild task SomeVer 😆).

[adamralph]

@robmen

1. Expose the various pieces of the git version to MSBuild. This allows us to do various string concatenations and (in some cases) math operations in MSBuild .targets files to address the various versions in our build system.

As stated in the README, MinVer already sets properties representing every part of the version. What more are you proposing?

2. Adds a boolean to include the default pre-release labels even when the tag has pre-release information. We use default pre-release labels like dev on all dev builds. After releasing an rc-1 we like the dev builds to still have the dev label, like 1.0.0-rc.1.dev.1. This is mostly a vanity feature, but it turned out to be pretty straightforward to wire in so I took a shot at it. If you like this feature, I'd also add it to the minver.exe to maintain consistency.

I'm not sure I understand the use case.

You tag and release 1.0.0-rc.1. You then push some commits to that branch which result in 1.0.0-rc.1.1, 1.0.0-rc.1.2, etc. At some point you tag and release 1.0.0-rc.2. Why does that not work for you?

[robmen]

1. Here's the full list of properties exposed:

   • Version
   • Major
   • Minor
   • Patch
   • Label
   • Sha - new
   • ShortSha - new
   • Height - new

2. It could work. Today we use labels akin to -rc.1.dev.#, and it was straightforward to enhance MinVer to continue to support it.

Let me know if there are any other questions I can answer.

[adamralph]

Here's the full list of properties exposed:

• Version
• Major
• Minor
• Patch
• Label
• Sha - new
• ShortSha - new
• Height - new

What is your use case for the SHA?

I would avoid using height in isolation. It's part of the pre-release identifiers, and they should really be treated as a discrete item and not broken apart. But I guess this is driven by your desire to insert dev before the height, so we should probably examine that first.

2. It could work. Today we use labels akin to -rc.1.dev.#, and it was straightforward to enhance MinVer to continue to support it.

What purpose does the dev serve? Is it enough to know that any pre-release version with an ordinal of x.y (e.g. rc.1.1) is a "dev" version? If you really do need dev as another indicator, I would suggest tagging it on at the end:

<Target Name="MyTarget" AfterTargets="MinVer" Condition="'$([System.String]::new($(MinVerPreRelease)).Split(`.`).Length)' == '3'" >
  <PropertyGroup>
    <PackageVersion>$(MinVerVersion).dev</PackageVersion>
    <Version>$(PackageVersion)</Version>
  </PropertyGroup>
</Target>

[adamralph]

BTW, in the .NET 8 SDK, it seems that SourceRevisionId will give you the SHA.

[robmen]

Ahh, sorry, I forgot to motivate the change. There are three goals in play.

1. The primary goal is to enable old-school four-part file versions. The height is used as the fourth digit in: {Major}.{Minor}.{Patch}.{Height}. That allows you to enable build-to-build upgrades when not using SemVer. However, I realize I've made a mistake and need the "full height" (the height since the last non-prerelease tag), not the height since the last tag. I'll need to fix that and probably rename the Height output property FullHeight (or a better name).

2. The goal for the SHA is to differentiate builds from different developers that may have the same height because they are working in private topic branches. The SourceRevisionId may work; I'd have to create a .NET 8 .csproj to verify. But MinVer knows the exact SHA for the candidate, so it was safest to return that directly.

3. The final goal is to enable our current way of differentiating "official builds" (releases without dev. label) from "dev builds" (releases with dev. label). Without the dev. feature, the first range of dev builds would be 1.0.0-dev.#. Then, after the first RC, dev builds would end in .# like 1.0.0-rc1.# and so on. It's easier to communicate with consumers that a dev build is a build with dev. in it (e.g. 1.0.0-dev.# and 1.0.0-rc1.dev.#).

Hopefully, I'm motivating the scenarios better. I will need to make that fix for full height, but I don't want to waste your time if you are not interested in adding any of these changes to MinVer. :)

[adamralph]

1. The primary goal is to enable old-school four-part file versions. The height is used as the fourth digit in: {Major}.{Minor}.{Patch}.{Height}. That allows you to enable build-to-build upgrades when not using SemVer. However, I realize I've made a mistake and need the "full height" (the height since the last non-prerelease tag), not the height since the last tag. I'll need to fix that and probably rename the Height output property FullHeight (or a better name).

I would advise against using the height for this. As stated in the FAQ, the official guidance for assembly file version states:

✔️ CONSIDER including a continuous integration build number as the AssemblyFileVersion revision.

The FAQ shows how to do that.

---

2. The goal for the SHA is to differentiate builds from different developers that may have the same height because they are working in private topic branches. The SourceRevisionId may work; I'd have to create a .NET 8 .csproj to verify. But MinVer knows the exact SHA for the candidate, so it was safest to return that directly.

SourceRevisionId should work for this. AFAIK you don't have to be targetting .NET 8, you just have to be using the .NET 8 SDK to build the project.

---

3. The final goal is to enable our current way of differentiating "official builds" (releases without dev. label) from "dev builds" (releases with dev. label). Without the dev. feature, the first range of dev builds would be 1.0.0-dev.#. Then, after the first RC, dev builds would end in .# like 1.0.0-rc1.# and so on. It's easier to communicate with consumers that a dev build is a build with dev. in it (e.g. 1.0.0-dev.# and 1.0.0-rc1.dev.#).

I would do this as I suggested in my previous answer, which would give you versions like 1.0.0-rc.1.1.dev. This requires no change to MinVer.

[robmen]

Alright, cool. Thank you very much for the insights.