Updates to account for changes in meaning of FileVersionQuad.Revision LSB (#38)

* Updates to account for changes in meaning of `FileVersionQuad.Reision` LSB
* Specs are silent on the point playground indicates that the LSB indicates a CI build (ODD) however, that would place a CI build as
a HIGHER sort order than the release form without special understanding. Which won't exist in any OS APIs. So the meaning is
inverted and the higher numeric ordering is reserved for release builds allowing for expected comparisons to work.
* Docs build updates
* Adjusted the build version to use a patch to the previously released
RC build.
* This is OK for the develop branch as nothing has released from it or any other version and the changes are relevant to the updated release.

* Removed unused source file causing build failures

---------

Co-authored-by: smaillet <25911635+smaillet@users.noreply.github.com>

Author: smaillet

BuildVersion.xml

@@ -2,8 +2,9 @@
 This file is updated on a public release to set the next build that pre-releases will increment to
 -->
 <BuildVersionData
-    BuildMajor = "6"
+    BuildMajor = "5"
     BuildMinor = "0"
     BuildPatch = "0"
-    PreReleaseName = "alpha"
+    PreReleaseName = "rc"
+    PreReleaseNumber = "1"
 />

New-GeneratedVersionProps.ps1

@@ -215,7 +215,8 @@ class CSemVer
 
         $this.OrderedVersion = [CSemVer]::GetOrderedVersion($this.Major, $this.Minor, $this.Patch, $this.PreReleaseVersion)
         $fileVer64 = $this.OrderedVersion -shl 1
-        if($this.CiBuildIndex -and $this.CiBuildName)
+        # If this is a release build include that in the file version
+        if(!$this.CiBuildIndex -and !$this.CiBuildName)
         {
             $fileVer64 += 1;
         }
@@ -366,7 +367,7 @@ try
     $propGroupElement.AppendChild($buildKindElement) | Out-Null
 
     # Unit tests need to see the CI build info as it isn't something they can determine on their own.
-    # The Build index is based on a timestamp and the build name depends on the runtime environment
+    # The Build index is based on a time stamp and the build name depends on the runtime environment
     # to set some env vars etc...
     if($buildKind -ne 'ReleaseBuild')
     {

README.md

@@ -36,17 +36,32 @@ you just built instead of the last one released publicly.
 ## Documentation
 Full documentation on the tasks is available in the project's [docs site](https://ubiquitydotnet.github.io/CSemVer.GitBuild/)
 
+>[!IMPORTANT]
+> There is one significant difference from the behavior in the official [CSemVer](https://csemver.org/).
+> Sadly the specs are silent on the issue of a File Version, and the [Playground](https://csemver.org/playground/site/#/)
+> hints that the LSB of the Revision field of a File Version "Quad" indicates a CI build (ODD).
+> ^1^. However, that would lead to FileVersion comparisons where all CI builds are ordered ahead
+> of any release builds of the same version number. This is backwards from the expressed intent.
+> Therefore, the Ubiquity.NET.Versioning libraries and task DO NOT do this. They implement the
+> exact opposite (LSB == RELEASE BUILD). That way any release builds have a sort order that is
+> greater than a CI build of the same version number.
+
 ## Building the tasks
 The build uses a common PowerShell module pattern for Ubiquity.NET projects. To build the sources
 use the `Build-All.ps1` script. You can also open the `src/Ubiquity.NET.Versioning.slnx` in any
 editor/IDE that has support for the slnx solution format. (Visual Studio 2022 is used but other
-options may work, though they are not supported. If you have experience then PRs are welcome for
-additional support - but such PRs ***MUST NOT*** break the VS support.)
+options may work, though they are not supported. If you have experience with other IDEs, then PRs
+are welcome for additional support - but such PRs ***MUST NOT*** break the VS support, and you
+must be willing to maintain such support going forward.)
 
 >[!IMPORTANT]
 > It is important to note that IDE builds of a clean repo get will FAIL! This is due to the
 > mechanisms used to eliminate circular dependencies while still supporting automated versioning
 > of the projects themselves. To resolve this, you must run the `.\New-GeneratedVersionProps.ps1`
 > at least once to create the imported `generatedversion.props` file. This is also generated by
-> the `Build-All.ps1` script, which is the recommended means of generaing the required file. This
+> the `Build-All.ps1` script, which is the recommended means of generating the required file. This
 > is only needed the first time (or any time the `buildversion.xml` changes).
+
+----
+^1^See: [This issue](https://github.com/CK-Build/csemver.org/issues/2) which was reported upon
+testing this library and found inconsistencies.

docfx/build-tasks/index.md

@@ -4,11 +4,12 @@ using a Constrained Semantic Version ([CSemVer](https://csemver.org/)).
 
 >[!WARNING]
 > As a [Breaking change in .NET SDK 8](https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/8.0/source-link)
-> is now setting the build meta data for the `InformationalVersion` property without user
-> consent. (A Highly controversial choice that was more easily handled via an OPT-IN pattern)
-> Unfortunately, this was set ON by default and made into an 'OPT-OUT' scenario. This library
-> will honor such a setting and does not alter/interfere with it in any way. (Though the results
-> can, unfortunately, produce surprising behavior).
+> is now setting the build meta data for the `InformationalVersion` property automatically and
+> without user consent. (A Highly controversial choice that was more easily handled via an
+> OPT-IN pattern) Unfortunately, this was set ON by default and made into an 'OPT-OUT' scenario.
+> This library will honor such a setting and does not alter/interfere with it in any way.
+> (Though the results can, unfortunately, produce surprising behavior as it is not well
+> documented).
 >
 > If you wish to disable this behavior you can set an MSBUILD property to OPT-OUT as follows:  
 > `<IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>`  
@@ -17,11 +18,12 @@ using a Constrained Semantic Version ([CSemVer](https://csemver.org/)).
 > who are aware of the change and those who use this library to set an explicit build meta data
 > string. (Principle of least surprise for what this library can control).
 >
-> The default .NET build behavior is to use the Repository ID (usually a GIT commit hash).
-> This is appended with a leading `+` if one isn't already in the `InformationalVersion`
-> property. If build metadata is already included (Like from use of this task) the id is
-> appended using a `.` instead. So it is ALWAYS appended unless the project has opted out of
-> this behavior by setting the property as previously described.
+> The default behavior added in this breaking change is to use the Repository ID (usually a GIT
+> commit hash [FULL SHA form!]) as the build metadata. This is appended with a leading `+` if
+> one isn't already in the `InformationalVersion` property. If build metadata is already
+> included (Like from use of this task) the id is appended using a `.` instead. So it is ALWAYS
+> appended unless the project has opted out of this behavior by setting the property as
+> previously described.
 >
 > Thus, it is ***strongly recommended*** that projects using this package OPT-OUT
 > of the new behavior.
@@ -36,15 +38,15 @@ allowing for automated CI builds. These new versions are called a [Constrained S
 Version](http://csemver.org) (CSemVer).
 
 A CSemVer is unique for each CI build and always increments while still supporting official
-releases. In the real world there are often cases where there are additional builds that are distinct from
-official releases and CI builds. Including Local developer builds, builds generated from a Pull 
-Request (a.k.a Automated buddy build). CSemVer doesn't explicitly define any format for these
-cases. So this library defines a pattern of versioning that is fully compatible with CSemVer and
-allows for the additional build types in a way that retains precedence having the least
-surprising consequences. In particular, local build packages have a higher precedence than CI or
-release versions if all other components of the version match. This ensures that what you are
-building includes the dependent packages you just built instead of the last one released
-publicly.
+releases. However, in the real world, there are often cases where there are additional builds
+that are distinct from official releases and CI builds. These include local developer builds
+and builds generated from a Pull Request (a.k.a Automated buddy build). Neither SemVer, nor
+CSemVer explicitly define any format for these cases. So this library defines a pattern of
+versioning that is fully compatible with CSemVer and allows for the additional build types
+in a way that retains precedence having the least surprising consequences. In particular,
+local build versions have a higher precedence than CI or release versions if all other
+components of the version match. This ensures that what you are building includes the dependent
+components you just built instead of the last one released publicly.
 
 The following is a list of the version formats in descending order of precedence:
 
@@ -56,24 +58,41 @@ The following is a list of the version formats in descending order of precedence
 | Official PreRelease | `{BuildMajor}.{BuildMinor}.{BuildPatch}-{PreReleaseName}[.PreReleaseNumber][.PreReleaseFix]+{BuildMeta}` |
 | Official Release | `{BuildMajor}.{BuildMinor}.{BuildPatch}+{BuildMeta}` |
 
+That is the, CI BuildName is chosen to ensure the ordering matches the expected behavior for
+a build.
+
 This project provides an MSBUILD task to automate the generation of these versions in an easy
 to use NuGet Package.
 
 The package creates File and Assembly Versions and defines the appropriate MsBuild properties
 so the build will automatically incorporate them.
 > **NOTE:**  
-The automatic use of MsBuild properties requires using the new SDK attribute support for .NET
-projects. Where the build auto generates the assembly info. If you are using some other means to
-auto generate the assembly level versioning attributes. You can use the properties generated by
-this package to generate the attributes.
+> The automatic use of MsBuild properties requires using the new SDK attribute support for .NET
+> projects. Where the build auto generates the assembly info. If you are using some other means
+> to auto generate the assembly level versioning attributes. You can use the properties
+> generated by this package to generate the attributes.
 
 File and AssemblyVersions are computed based on the CSemVer "Ordered version", which
-is a 64 bit value that maps to a standard windows FILEVERSION Quad with each part
-consuming 16 bits. This ensures a strong relationship between the  assembly/file versions
+is a 64 bit value that maps to a standard windows FILE VERSION Quad with each part
+consuming 16 bits. This ensures a strong relationship between the assembly/file versions
 and the packages as well as ensures that CI builds can function properly. Furthermore, this
 guarantees that each build has a different file and assembly version so that strong name
 signing functions properly to enable loading different versions in the same process.
 
+>[!IMPORTANT]
+> A file version quad representation of a CSemVer does NOT carry with it the CI information nor
+> the build metadata. It only contains a single bit to indicate a Release vs. a CI build. In
+> fact, the official CSemVer specs are silent on the use of this bit though the "playground"
+> does indicate an ODD numbered revision is a CI build. However, that leads to problems (see
+> this: [Spec issue](https://github.com/CK-Build/csemver.org/issues/2) for more details).
+> Thus, the `Ubiquity.NET.Versioning.*` libraries do NOT work that way. In these libraries,
+> an odd numbered revision indicates a RELEASE build whereas an EVEN numbered form represents
+> a CI build. This results in the correct behavior for comparisons of the File version. The
+> file version comparisons MUST result in correct ordering or an underlying Windows OS and
+> related APIs will NOT behave as expected. (A CI build is ALWAYS ordered less then a release
+> build)
+
+
 The Major, Minor and Patch versions are only updated in the primary branch at the time
 of a release. This ensures the concept that SemVer versions define released products. The
 version numbers used are stored in the repository in the BuildVersion.xml

docfx/docfx.json

@@ -67,15 +67,16 @@
         ],
         "template": [
             "default",
-            "modern"
+            "modern",
+            "templates/Ubiquity"
         ],
         "globalMetadataFiles": [],
         "fileMetadataFiles": [],
         "postProcessors": [],
         "globalMetadata": {
             "_appTitle": "Ubiquity.NET",
             "_appFooter": "Copyright (C) 2017-2025, Ubiquity.NET Contributors",
-            "_appLogoPath": "favicon-32x32.png", // TODO: change this to something more generic...
+            "_appLogoPath": "favicon-32x32.png",
             "_disableBreadcrumb": true,
             "_gitContribute": {
                 "repo": "https://github.com/UbiquityDotNET/CSemVer.GitBuild",

docfx/templates/Ubiquity/public/main.css

@@ -0,0 +1,9 @@
+@charset "UTF-8";
+
+/*
+Disable display of inherited members. It would be nice if there was a build option to not even generate this noise,
+but sadly, there is none so this disables the final render of such things.
+*/
+.typelist.inheritedMembers {
+    display: none
+}

docfx/templates/Ubiquity/readme.md

@@ -0,0 +1,4 @@
+# Ubiquity DOCFX template
+This template adds support to the modern template to disable some features like inherited members. It
+would be nice if docfx didn't even generate such things, but it has non knobs to control that so it can
+only be disabled by a custom CSS to hide the content at page render time on the client...

src/Ubiquity.NET.Versioning.Build.Tasks/CreateVersionInfo.cs

@@ -170,8 +170,8 @@ private void SetFileVersion( int preRelIndex )
 
             Log.LogMessage(MessageImportance.Low, "orderedVersion={0}", orderedVersion);
 
-            bool isCiBuild = !string.IsNullOrWhiteSpace(CiBuildIndex) && !string.IsNullOrWhiteSpace(CiBuildName);
-            UInt64 fileVersion64 = (orderedVersion << 1) + (isCiBuild ? 1ul : 0ul);
+            bool isReleaseBuild = string.IsNullOrWhiteSpace(CiBuildIndex) && string.IsNullOrWhiteSpace(CiBuildName);
+            UInt64 fileVersion64 = (orderedVersion << 1) + (isReleaseBuild ? 1ul : 0ul);
             FileVersionRevision = (UInt16)(fileVersion64 % 65536);
 
             UInt64 rem = (fileVersion64 - FileVersionRevision.Value) / 65536;

src/Ubiquity.NET.Versioning.UT/CSemVerTests.cs

@@ -209,13 +209,13 @@ public static void VerifyOrderedVersionPair(
             Assert.AreEqual(number, ver.PrereleaseVersion.Number, exp);
             Assert.AreEqual(fix, ver.PrereleaseVersion.Fix, exp);
             Assert.IsFalse(ver.CiBuildInfo.IsValid, exp);
-            Assert.IsFalse(ver.IsCIBuild, exp);
+            Assert.IsTrue(ver.IsCIBuild, exp, $"Conversion from integer should still indicate it IS a CI build for '{exp}'");
             Assert.IsNotNull(ver.BuildMetaData, $"non-nullable property should not be null for '{exp}'");
             Assert.AreEqual(string.Empty, ver.BuildMetaData, $"non-nullable property should be an empty string if not set '{exp}'");
             Assert.AreEqual(orderedVersion, ver.OrderedVersion, exp);
             Assert.AreEqual(f64, ver.FileVersion, exp);
 
-            // Now test CI variant
+            // Now test Release variant
             var f64CI = FileVersionQuad.From((orderedVersion << 1) + 1);
             var verCI = CSemVer.From(f64CI.ToUInt64());
             Assert.AreEqual(major, verCI.Major, exp);
@@ -227,7 +227,7 @@ public static void VerifyOrderedVersionPair(
             Assert.AreEqual(number, verCI.PrereleaseVersion.Number, exp);
             Assert.AreEqual(fix, verCI.PrereleaseVersion.Fix, exp);
             Assert.IsFalse(verCI.CiBuildInfo.IsValid, $"Conversion from integer should NOT have any CI build info for '{exp}'");
-            Assert.IsTrue(verCI.IsCIBuild, $"Conversion from integer should still indicate it IS a CI build for '{exp}'");
+            Assert.IsFalse(verCI.IsCIBuild, $"Conversion from integer should indicate it IS a release build for '{exp}'");
             Assert.IsNotNull(verCI.BuildMetaData, $"non-nullable property should not be null for '{exp}'");
             Assert.AreEqual(string.Empty, verCI.BuildMetaData, $"non-nullable property should be an empty string if not set '{exp}'");
             Assert.AreEqual(orderedVersion, verCI.OrderedVersion , $"CI builds should have the same ordered version number as a non-CI build for '{exp}'");
@@ -250,13 +250,13 @@ public static void VerifyOrderedVersionPair(
             Assert.IsFalse(ver.PrereleaseVersion.IsValid, exp);
             Assert.IsFalse(ver.IsPrerelease, exp);
             Assert.IsFalse(ver.CiBuildInfo.IsValid, exp);
-            Assert.IsFalse(ver.IsCIBuild, exp);
+            Assert.IsTrue(ver.IsCIBuild, exp, $"Conversion from integer should still indicate it IS a CI build for '{exp}'");
             Assert.IsNotNull(ver.BuildMetaData, $"non-nullable property should not be null for '{exp}'");
             Assert.AreEqual(string.Empty, ver.BuildMetaData, $"non-nullable property should be an empty string if not set for '{exp}'");
             Assert.AreEqual(orderedVersion, ver.OrderedVersion, exp);
             Assert.AreEqual(f64, ver.FileVersion, exp);
 
-            // Now test CI variant
+            // Now test Release variant
             var f64CI = FileVersionQuad.From((orderedVersion << 1) + 1);
             var verCI = CSemVer.From(f64CI.ToUInt64());
             Assert.AreEqual(major, verCI.Major, exp);
@@ -265,7 +265,7 @@ public static void VerifyOrderedVersionPair(
             Assert.IsFalse(verCI.PrereleaseVersion.IsValid, exp);
             Assert.IsFalse(verCI.IsPrerelease, exp);
             Assert.IsFalse(verCI.CiBuildInfo.IsValid, $"Conversion from integer should NOT have any CI build info for '{exp}'");
-            Assert.IsTrue(verCI.IsCIBuild, $"Conversion from integer should indicate it IS a CI build for '{exp}'");
+            Assert.IsFalse(verCI.IsCIBuild, $"Conversion from integer should indicate it IS a release build for '{exp}'");
             Assert.IsNotNull(verCI.BuildMetaData, $"non-nullable property should not be null for '{exp}'");
             Assert.AreEqual(string.Empty, verCI.BuildMetaData, $"non-nullable property should be an empty string if not set for '{exp}'");
             Assert.AreEqual(orderedVersion, verCI.OrderedVersion , $"CI builds should have the same ordered version number as a non-CI build for '{exp}'");

src/Ubiquity.NET.Versioning.UT/FileVersionQuadTests.cs

@@ -41,6 +41,10 @@ public void CompareToTest( )
             var val = new FileVersionQuad(0x1234, 0x5678, 0x9ABC, 0xDEF0 );
             var valp1 = new FileVersionQuad(0x1234, 0x5678, 0x9ABC, 0xDEF1 );
 
+            Assert.IsFalse(valm1.IsCiBuild);
+            Assert.IsTrue(val.IsCiBuild);
+            Assert.IsFalse(valp1.IsCiBuild);
+
             Assert.AreEqual(-1, valm1.CompareTo(val), "(val-1) < val");
             Assert.AreEqual(-1, valm1.CompareTo(valp1), "(val-1) < (val+1)");
             Assert.AreEqual(1, val.CompareTo(valm1), "val > (val-1)");