Added support for CSemVer v1.0.0-rc.1 pre-release formatting (#26)

Author: smaillet

Show-Docs.ps1

@@ -5,20 +5,17 @@ using module "PSModules/RepoBuild/RepoBuild.psd1"
 .SYNOPSIS
     Shows docs using the docfx built-in server
 
-.PARAMETER DocsPathToHost
-    Path of docs to host. Default is the local build but any legit path is accepted.
-    This is useful when downloading docs build artifacts to ensure they are built correctly.
-
 .PARAMETER buildInfo
    BuildInfo to use for current repo build. The hashtable provided for this must include the
    `DocsOutputPath` value for the path to use. This is normally set by a call to `Initialize-Environment`
+
+.PARAMETER DocsPathToHost
+    Path of docs to host. Default is the local build but any legit path is accepted.
+    This is useful when downloading docs build artifacts to ensure they are built correctly.
 #>
 Param(
-    [Parameter(Mandatory, ParameterSetName = 'UsePath', Position = 0)]
-    [string]$DocsPathToHost,
-
-    [Parameter(ParameterSetName = 'UseRepo', Position = 0)]
-    [hashtable]$buildInfo
+    [hashtable]$buildInfo,
+    [string]$DocsPathToHost
 )
 
 $docFXToolVersion = '2.78.3'
@@ -30,7 +27,7 @@ Push-Location $PSScriptRoot
 $oldPath = $env:Path
 try
 {
-    if ($PSCmdlet.ParameterSetName -eq 'UseRepo')
+    if (!$DocsPathToHost)
     {
         if (!$buildInfo)
         {

docfx/build-tasks/index.md

@@ -17,13 +17,13 @@ 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 OPT-OUT 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. Unless the project has opted out of this behavior by setting the property as
-> previously described.
+> 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.
 >
->Thus, it is ***strongly recommended*** that projects using this package OPT-OUT
+> Thus, it is ***strongly recommended*** that projects using this package OPT-OUT
 > of the new behavior.
 
 
@@ -50,13 +50,13 @@ The following is a list of the version formats in descending order of precedence
 
 | Build Type | Format |
 |------------|--------|
-| Local build  | `{BuildMajor}.{BuildMinor}.{BuildPatch}--ci-{UTCTIME of build }-ZZZ` |
-| Pull Request | `{BuildMajor}.{BuildMinor}.{BuildPatch}--ci-{UTCTIME of PR Commit}-PRQ+{COMMIT ID}` |
-| Official CI builds | `{BuildMajor}.{BuildMinor}.{BuildPatch}--ci-{UTCTIME of HEAD Commit}-BLD+{COMMIT ID}` |
-| Official PreRelease | `{BuildMajor}.{BuildMinor}.{BuildPatch}-{PreReleaseName}[.PreReleaseNumber][.PreReleaseFix]+{COMMIT ID}` |
-| Official Release | `{BuildMajor}.{BuildMinor}.{BuildPatch}+{COMMIT ID}` |
+| Local build  | `{BuildMajor}.{BuildMinor}.{BuildPatch}--ci-{CiBuildIndex}-ZZZ+{BuildMeta}` |
+| Pull Request | `{BuildMajor}.{BuildMinor}.{BuildPatch}--ci-{CiBuildIndex}-PRQ+{BuildMeta}` |
+| Official CI builds | `{BuildMajor}.{BuildMinor}.{BuildPatch}--ci-{CiBuildIndex}-BLD+{BuildMeta}` |
+| Official PreRelease | `{BuildMajor}.{BuildMinor}.{BuildPatch}-{PreReleaseName}[.PreReleaseNumber][.PreReleaseFix]+{BuildMeta}` |
+| Official Release | `{BuildMajor}.{BuildMinor}.{BuildPatch}+{BuildMeta}` |
 
-This package provides a single package to automate the generation of these versions in an easy
+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
@@ -92,6 +92,9 @@ CSemVer.Build uses MSBuild properties to determine the final version number.
 | BuildMeta         | `<undefined>`                                                | Build meta for the version
 | CiBuildIndex      | ISO 8601 formated UTC time-stamp for the build or the commit ID for automated builds | Provides a unique build to build value guaranteed to increase with each build
 | CiBuildName       | `<see notes>`                                                | CSemVer CI name
+| PackageVersionUsesShortForm | `<Undefined>` => false | Determines if the PackageVersion is set to the short form for legacy NuGet clients |
+| GeneratedVersionInfoHeader | `<undefined>` | Full path of the header file to generate [No header generated if not set] [Only applies to a VCXPROJ file ] |
+| GenerateAssemblyInfo | `<undefined>` | If set, creates `$(IntermediateOutputPath)AssemblyVersionInfo.g.cs` and includes it for compilation. Used for legacy CSPROJ files as new SDK projects handle this automatically now |
 
 ### CiBuildName
 Unless explicitly provided, the CiBuildName is determined by a set of properties that indicate
@@ -124,6 +127,11 @@ example for setting them based on an AppVeyor build in the `Directory.Build.prop
 </PropertyGroup>
 ```
 
+### PackageVersionUsesShortForm
+The MSBuild Property `PackageVersionUsesShortForm` is used by the task to determine the format to use for the
+`PackageVersion` property. The default is to use the long form supported by modern NuGet clients, however if your are
+in need of the legacy format support a project may set this property to `true` to observe the legacy behavior.
+
 ## BuildVersion.xml
 If the MSBuild property `BuildMajor` is not set, then the base build version is read from the
 repository file specified in the BuildVersion.xml, typically this is located at the root of a
@@ -132,13 +140,71 @@ the file is specified by an MSBuild property `BuildVersionXml`. The contents of
 fairly simple and only requires a single `BuildVersionData` element with a set of attributes.
 The available attributes are:
 
-|Name               |Description|
-|-------------------|-----------|
-| BuildMajor        | Major portion of the build number |
-| BuildMinor        | Minor portion of the build number |
-| BuildPatch        | Patch portion of the build number |
-| PreReleaseName    | PreRelease Name of the CSemVer |
-| PreReleaseNumber  | PreRelease Number of the CSemVer |
-| PreReleaseFix     | PreRelease Fix of the CSemVer |
+|Name              |Description|
+|------------------|-----------|
+| BuildMajor       | Major portion of the build number |
+| BuildMinor       | Minor portion of the build number |
+| BuildPatch       | Patch portion of the build number |
+| PreReleaseName   | PreRelease Name of the CSemVer |
+| PreReleaseNumber | PreRelease Number of the CSemVer |
+| PreReleaseFix    | PreRelease Fix of the CSemVer |
 
 Only the Major, minor and Patch numbers are required.
+Example:  
+```xml
+<BuildVersionData
+    BuildMajor = "5"
+    BuildMinor = "0"
+    BuildPatch = "0"
+    PreReleaseName = "alpha"
+/>
+```
+
+## Generated Properties
+|Name                |Description|
+|--------------------|-----------|
+| BuildTime          | Set to the current time (UTC ISO-8601 format) if not already set by build tooling) |
+| IsAutomatedBuild   | Automated build system value to indicate this is an automated build |
+| IsPullRequestBuild | Automated build system value to indicate this is a build for an untrusted PR |
+| IsReleaseBuild     | Automated build system value to indicate this is an official release build (No CI information) |
+| CiBuildName        | If not set externally, this is set based on the kind of build |
+| CiBuildIndex       | If not set externally, this is set based on the $(BuildTime) property by parsing the ISO-8601 string and computing an index from that |
+| BuildMajor         | Major portion of the build; If not set externally, this is set based on the information in the $(BuildVersionXml) file |
+| BuildMinor         | Minor portion of the build; If not set externally, this is set based on the information in the $(BuildVersionXml) file |
+| BuildPatch         | Patch portion of the build; If not set externally, this is set based on the information in the $(BuildVersionXml) file |
+| PreReleaseName     | PreRelease Name for the build [Optional]; If not set externally, this is set based on the information in the $(BuildVersionXml) file, which may not include a value for this |
+| PreReleaseNumber   | PreRelease Number for the build [Optional]; If not set externally, this is set based on the information in the $(BuildVersionXml) file, which may not include a value for this |
+| PreReleaseFix      | PreRelease Fix for the build [Optional]; If not set externally, this is set based on the information in the $(BuildVersionXml) file, which may not include a value for this |
+| FullBuildNumber    | String form of the full CSemVer value for a build |
+| ShortBuildNumber   | Short form of the CSemVer for use with legacy NuGet clients (Modern clients support the full name) |
+| FileVersionMajor   | Major portion of the FileVersion number (Used for vcxproj files to generate the version header) |
+| FileVersionMinor   | Minor portion of the FileVersion number (Used for vcxproj files to generate the version header) |
+| FileVersionBuild   | Build portion of the FileVersion number (Used for vcxproj files to generate the version header) |
+| FileVersionRevision | Revision portion of the FileVersion number (Used for vcxproj files to generate the version header) |
+
+### BuildTime
+Ordinarily this is set for an entire solution by build scripting to ensure that all components using this
+build task report the same version number. If it is not set the current time at the moment of property evaluation
+for a project is used. This will result in a distinct CI version for each project in a solution. Whether, that
+is desired or not is left for the consumer. If it is not desired, then a centralized setting as a build property
+or environment variable is warranted.
+
+## Automated build flags
+`IsAutomatedBuild`, `IsPullRequestBuild`, and `IsReleaseBuild` are normally set by an automated build script/action
+based on the build environment used and aid in determining the CI build name as previously described in
+[CiBuildName](#cibuildname).
+
+## CiBuildName
+If not explicitly set this is determined by the automated build flags as described in the [CiBuildName](#cibuildname)
+section of this document.
+
+## Detected Error Conditions
+|Code     |Description|
+|---------|-----------|
+| CSM001  | BuildMajor is a required property, either set it as a global or in the build version XML |
+| CSM002  | BuildMinor is a required property, either set it as a global or in the build version XML |
+| CSM003  | BuildPatch is a required property, either set it as a global or in the build version XML |
+| CSM004  | FileVersion property not provided AND FileVersionMajor property not found to create it from |
+| CSM005  | FileVersion property not provided AND FileVersionMinor property not found to create it from |
+| CSM006  | FileVersion property not provided AND FileVersionBuild property not found to create it from |
+| CSM007  | FileVersion property not provided AND FileVersionRevision property not found to create it from |

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

@@ -92,7 +92,7 @@ public override bool Execute( )
                 CSemVer = CreateSemVerString( preRelIndex );
                 Log.LogMessage(MessageImportance.Low, "CSemVer={0}", CSemVer ?? string.Empty);
 
-                ShortCSemVer = CreateSemVerString( preRelIndex, useShortForm: true );
+                ShortCSemVer = CreateSemVerString( preRelIndex, useShortForm: true, includeMetadata: false );
                 Log.LogMessage(MessageImportance.Low, "ShortCSemVer={0}", ShortCSemVer ?? string.Empty);
 
                 SetFileVersion( preRelIndex );
@@ -109,9 +109,21 @@ public override bool Execute( )
             }
         }
 
-        private string CreateSemVerString( int preRelIndex, bool useShortForm = false, bool includeMetadata = true )
+        /// <summary>Creates a formatted CSemver from the properties of this instance</summary>
+        /// <param name="preRelIndex">Numeric form of the build index [(-1)-7] where -1 indicates not a pre-release</param>
+        /// <param name="useShortForm">Flag to indicate if the short form is desired</param>
+        /// <param name="includeMetadata">Flag to indicate if the metadata is included</param>
+        /// <param name="alwaysIncludeZero">Flag to indicate if a 0 pre-release is ALWAYs included [see remarks]</param>
+        /// <returns>Formatted CSemVer string</returns>
+        /// <remarks>
+        /// <para>The <paramref name="alwaysIncludeZero"/> is for legacy behavior and should generally be left at the default. In
+        /// prior releases the pre-release number and fix were always included for pre-release builds in the short form. In
+        /// the current version based on CSemVer v1.0.0-rc.1 the behavior is the same as for a full version. (The Number is omitted
+        /// unless it is > 0 OR Fix >0).</para>
+        /// <para>Additionally, the short form uses a two digit leading 0 conversion.</para>
+        /// </remarks>
+        private string CreateSemVerString( int preRelIndex, bool useShortForm = false, bool includeMetadata = true, bool alwaysIncludeZero = false)
         {
-            bool alwaysIncludeZero = useShortForm;
             var bldr = new StringBuilder()
                           .AppendFormat(CultureInfo.InvariantCulture, "{0}.{1}.{2}", BuildMajor, BuildMinor, BuildPatch);
 
@@ -123,10 +135,10 @@ private string CreateSemVerString( int preRelIndex, bool useShortForm = false, b
 
                 if(PreReleaseNumber > 0 || PreReleaseFix > 0 || alwaysIncludeZero)
                 {
-                    bldr.AppendFormat( CultureInfo.InvariantCulture, ".{0}", PreReleaseNumber );
+                    bldr.AppendFormat( CultureInfo.InvariantCulture, useShortForm ? "{0:D02}" : ".{0}", PreReleaseNumber );
                     if(PreReleaseFix > 0 || alwaysIncludeZero)
                     {
-                        bldr.AppendFormat( CultureInfo.InvariantCulture, ".{0}", PreReleaseFix );
+                        bldr.AppendFormat( CultureInfo.InvariantCulture, useShortForm ? "-{0:D02}" : ".{0}", PreReleaseFix );
                     }
                 }
             }
@@ -251,6 +263,15 @@ private bool ValidateInput( )
             return !hasInputError;
         }
 
+        //private void LogError(
+        //    string code,
+        //    /*[StringSyntax(StringSyntaxAttribute.CompositeFormat)]*/ string message,
+        //    params object[] messageArgs
+        //    )
+        //{
+        //    Log.LogError("Task", code, null, null, 0, 0, 0, 0, message, messageArgs);
+        //}
+
         private static int ComputePreReleaseIndex( string preRelName )
         {
             int index = Find( PreReleaseNames, preRelName ).Index;

src/Ubiquity.NET.Versioning.Build.Tasks/build/Ubiquity.NET.Versioning.Build.Tasks.targets

@@ -54,11 +54,11 @@
                            BuildMeta = "$(BuildMeta)"
                            >
             <Output TaskParameter="CSemVer" PropertyName="FullBuildNumber" />
+            <Output TaskParameter="ShortCSemVer" PropertyName="ShortBuildNumber"/>
             <Output TaskParameter="FileVersionMajor" PropertyName="FileVersionMajor" />
             <Output TaskParameter="FileVersionMinor" PropertyName="FileVersionMinor" />
             <Output TaskParameter="FileVersionBuild" PropertyName="FileVersionBuild" />
             <Output TaskParameter="FileVersionRevision" PropertyName="FileVersionRevision" />
-            <Output TaskParameter="ShortCSemVer" PropertyName="PackageVersion"/>
         </CreateVersionInfo>
     </Target>
 
@@ -68,6 +68,12 @@
             <FileVersion Condition="'$(FileVersion)'==''">$(__FileVersion)</FileVersion>
             <AssemblyVersion Condition="'$(AssemblyVersion)'==''">$(__FileVersion)</AssemblyVersion>
             <InformationalVersion Condition="$(InformationalVersion)==''">$(FullBuildNumber)</InformationalVersion>
+            <!--
+            NuGet clients prior to 4.3.0 don't support the full name, and instead should use the short name.
+            Default is to use the newer format, but allow specification of the legacy format if needed.
+            -->
+            <PackageVersion Condition="$(FullBuildNumber)!='' AND '$(PackageVersionUsesShortForm)'!='true'">$(FullBuildNumber)</PackageVersion>
+            <PackageVersion Condition="$(ShortBuildNumber)!='' AND '$(PackageVersionUsesShortForm)'=='true'">$(ShortBuildNumber)</PackageVersion>
         </PropertyGroup>
     </Target>