1616
1717
1818
19- < meta name ="docfx:docurl " content ="https://github.com/UbiquityDotNET/Llvm.NET /blob/develop/docfx/build-tasks/index.md/#L1 ">
19+ < meta name ="docfx:docurl " content ="https://github.com/UbiquityDotNET/CSemVer.GitBuild /blob/develop/docfx/build-tasks/index.md/#L1 ">
2020 < meta name ="loc:inThisArticle " content ="In this article ">
2121 < meta name ="loc:searchResultsCount " content ="{count} results for "{query}" ">
2222 < meta name ="loc:searchNoResults " content ="No results for "{query}" ">
4444 < nav id ="autocollapse " class ="navbar navbar-expand-md " role ="navigation ">
4545 < div class ="container-xxl flex-nowrap ">
4646 < a class ="navbar-brand " href ="../index.html ">
47- < img id ="logo " class ="svg " src ="../llvm/DragonSharp48x48 .png " alt ="">
47+ < img id ="logo " class ="svg " src ="../favicon-32x32 .png " alt ="">
4848
4949 </ a >
5050 < button class ="btn btn-lg d-md-none border-0 " type ="button " data-bs-toggle ="collapse " data-bs-target ="#navpanel " aria-controls ="navpanel " aria-expanded ="false " aria-label ="Toggle navigation ">
@@ -87,21 +87,23 @@ <h1 id="about">About</h1>
8787< div class ="WARNING ">
8888< h5 > Warning</ h5 >
8989< p > As a < a href ="https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/8.0/source-link "> Breaking change in .NET SDK 8</ a >
90- is now setting the build meta data for the < code > InformationalVersion</ code > property without user
91- consent. (A Highly controversial choice that was more easily handled via an OPT-IN pattern)
92- Unfortunately, this was set ON by default and made into an 'OPT-OUT' scenario. This library
93- will honor such a setting and does not alter/interfere with it in any way. (Though the results
94- can, unfortunately, produce surprising behavior).</ p >
90+ is now setting the build meta data for the < code > InformationalVersion</ code > property automatically and
91+ without user consent. (A Highly controversial choice that was more easily handled via an
92+ OPT-IN pattern) Unfortunately, this was set ON by default and made into an 'OPT-OUT' scenario.
93+ This library will honor such a setting and does not alter/interfere with it in any way.
94+ (Though the results can, unfortunately, produce surprising behavior as it is not well
95+ documented).</ p >
9596< p > If you wish to disable this behavior you can set an MSBUILD property to OPT-OUT as follows:< br >
9697< code > <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion></ code > </ p >
9798< p > This choice of ignoring the additional data is considered to have the least impact on those
9899who are aware of the change and those who use this library to set an explicit build meta data
99100string. (Principle of least surprise for what this library can control).</ p >
100- < p > The default .NET build behavior is to use the Repository ID (usually a GIT commit hash).
101- This is appended with a leading < code > +</ code > if one isn't already in the < code > InformationalVersion</ code >
102- property. If build metadata is already included (Like from use of this task) the id is
103- appended using a < code > .</ code > instead. So it is ALWAYS appended unless the project has opted out of
104- this behavior by setting the property as previously described.</ p >
101+ < p > The default behavior added in this breaking change is to use the Repository ID (usually a GIT
102+ commit hash [FULL SHA form!]) as the build metadata. This is appended with a leading < code > +</ code > if
103+ one isn't already in the < code > InformationalVersion</ code > property. If build metadata is already
104+ included (Like from use of this task) the id is appended using a < code > .</ code > instead. So it is ALWAYS
105+ appended unless the project has opted out of this behavior by setting the property as
106+ previously described.</ p >
105107< p > Thus, it is < em > < strong > strongly recommended</ strong > </ em > that projects using this package OPT-OUT
106108of the new behavior.</ p >
107109</ div >
@@ -113,15 +115,15 @@ <h2 id="overview">Overview</h2>
113115allowing for automated CI builds. These new versions are called a < a href ="http://csemver.org "> Constrained Semantic
114116Version</ a > (CSemVer).</ p >
115117< p > A CSemVer is unique for each CI build and always increments while still supporting official
116- releases. In the real world there are often cases where there are additional builds that are distinct from
117- official releases and CI builds. Including Local developer builds, builds generated from a Pull
118- Request (a.k.a Automated buddy build). CSemVer doesn't explicitly define any format for these
119- cases. So this library defines a pattern of versioning that is fully compatible with CSemVer and
120- allows for the additional build types in a way that retains precedence having the least
121- surprising consequences. In particular, local build packages have a higher precedence than CI or
122- release versions if all other components of the version match. This ensures that what you are
123- building includes the dependent packages you just built instead of the last one released
124- publicly.</ p >
118+ releases. However, in the real world, there are often cases where there are additional builds
119+ that are distinct from official releases and CI builds. These include local developer builds
120+ and builds generated from a Pull Request (a.k.a Automated buddy build). Neither SemVer, nor
121+ CSemVer explicitly define any format for these cases. So this library defines a pattern of
122+ versioning that is fully compatible with CSemVer and allows for the additional build types
123+ in a way that retains precedence having the least surprising consequences. In particular,
124+ local build versions have a higher precedence than CI or release versions if all other
125+ components of the version match. This ensures that what you are building includes the dependent
126+ components you just built instead of the last one released publicly.</ p >
125127< p > The following is a list of the version formats in descending order of precedence:</ p >
126128< table >
127129< thead >
@@ -153,23 +155,39 @@ <h2 id="overview">Overview</h2>
153155</ tr >
154156</ tbody >
155157</ table >
158+ < p > That is the, CI BuildName is chosen to ensure the ordering matches the expected behavior for
159+ a build.</ p >
156160< p > This project provides an MSBUILD task to automate the generation of these versions in an easy
157161to use NuGet Package.</ p >
158162< p > The package creates File and Assembly Versions and defines the appropriate MsBuild properties
159163so the build will automatically incorporate them.</ p >
160164< blockquote >
161165< p > < strong > NOTE:</ strong > < br >
162166The automatic use of MsBuild properties requires using the new SDK attribute support for .NET
163- projects. Where the build auto generates the assembly info. If you are using some other means to
164- auto generate the assembly level versioning attributes. You can use the properties generated by
165- this package to generate the attributes.</ p >
167+ projects. Where the build auto generates the assembly info. If you are using some other means
168+ to auto generate the assembly level versioning attributes. You can use the properties
169+ generated by this package to generate the attributes.</ p >
166170</ blockquote >
167171< p > File and AssemblyVersions are computed based on the CSemVer "Ordered version", which
168- is a 64 bit value that maps to a standard windows FILEVERSION Quad with each part
169- consuming 16 bits. This ensures a strong relationship between the assembly/file versions
172+ is a 64 bit value that maps to a standard windows FILE VERSION Quad with each part
173+ consuming 16 bits. This ensures a strong relationship between the assembly/file versions
170174and the packages as well as ensures that CI builds can function properly. Furthermore, this
171175guarantees that each build has a different file and assembly version so that strong name
172176signing functions properly to enable loading different versions in the same process.</ p >
177+ < div class ="IMPORTANT ">
178+ < h5 > Important</ h5 >
179+ < p > A file version quad representation of a CSemVer does NOT carry with it the CI information nor
180+ the build metadata. It only contains a single bit to indicate a Release vs. a CI build. In
181+ fact, the official CSemVer specs are silent on the use of this bit though the "playground"
182+ does indicate an ODD numbered revision is a CI build. However, that leads to problems (see
183+ this: < a href ="https://github.com/CK-Build/csemver.org/issues/2 "> Spec issue</ a > for more details).
184+ Thus, the < code > Ubiquity.NET.Versioning.*</ code > libraries do NOT work that way. In these libraries,
185+ an odd numbered revision indicates a RELEASE build whereas an EVEN numbered form represents
186+ a CI build. This results in the correct behavior for comparisons of the File version. The
187+ file version comparisons MUST result in correct ordering or an underlying Windows OS and
188+ related APIs will NOT behave as expected. (A CI build is ALWAYS ordered less then a release
189+ build)</ p >
190+ </ div >
173191< p > The Major, Minor and Patch versions are only updated in the primary branch at the time
174192of a release. This ensures the concept that SemVer versions define released products. The
175193version numbers used are stored in the repository in the BuildVersion.xml</ p >
@@ -448,6 +466,7 @@ <h2 id="cibuildname-1">CiBuildName</h2>
448466< p > If not explicitly set this is determined by the automated build flags as described in the < a href ="#cibuildname "> CiBuildName</ a >
449467section of this document.</ p >
450468< h2 id ="detected-error-conditions "> Detected Error Conditions</ h2 >
469+ < h3 id ="targets-file "> Targets file</ h3 >
451470< table >
452471< thead >
453472< tr >
@@ -486,11 +505,95 @@ <h2 id="detected-error-conditions">Detected Error Conditions</h2>
486505</ tr >
487506</ tbody >
488507</ table >
508+ < h3 id ="createversioninfo-task "> CreateVersionInfo Task</ h3 >
509+ < table >
510+ < thead >
511+ < tr >
512+ < th > Code</ th >
513+ < th > Description</ th >
514+ </ tr >
515+ </ thead >
516+ < tbody >
517+ < tr >
518+ < td > CSM100</ td >
519+ < td > BuildMajor value must be in range [0-99999]</ td >
520+ </ tr >
521+ < tr >
522+ < td > CSM101</ td >
523+ < td > BuildMinor value must be in range [0-49999]</ td >
524+ </ tr >
525+ < tr >
526+ < td > CSM102</ td >
527+ < td > BuildPatch value must be in range [0-9999]</ td >
528+ </ tr >
529+ < tr >
530+ < td > CSM103</ td >
531+ < td > PreReleaseName is unknown</ td >
532+ </ tr >
533+ < tr >
534+ < td > CSM104</ td >
535+ < td > PreReleaseNumber value must be in range [0-99]</ td >
536+ </ tr >
537+ < tr >
538+ < td > CSM105</ td >
539+ < td > PreReleaseFix value must be in range [0-99]</ td >
540+ </ tr >
541+ < tr >
542+ < td > CSM106< sup > 1</ sup > </ td >
543+ < td > If CiBuildIndex is set then CiBuildName must also be set; If CiBuildIndex is NOT set then CiBuildName must not be set.</ td >
544+ </ tr >
545+ < tr >
546+ < td > CSM107</ td >
547+ < td > CiBuildIndex does not match syntax defined by CSemVer</ td >
548+ </ tr >
549+ < tr >
550+ < td > CSM108</ td >
551+ < td > CiBuildName does not match syntax defined by CSemVer</ td >
552+ </ tr >
553+ </ tbody >
554+ </ table >
555+ < h3 id ="parsebuildversionxml-task "> ParseBuildVersionXml Task</ h3 >
556+ < table >
557+ < thead >
558+ < tr >
559+ < th > Code</ th >
560+ < th > Description</ th >
561+ </ tr >
562+ </ thead >
563+ < tbody >
564+ < tr >
565+ < td > CSM200</ td >
566+ < td > BuildVersionXml is required and must not be all whitespace</ td >
567+ </ tr >
568+ < tr >
569+ < td > CSM201</ td >
570+ < td > Specified BuildVersionXml does not exist < code > $(BuildVersionXml)</ code > </ td >
571+ </ tr >
572+ < tr >
573+ < td > CSM202</ td >
574+ < td > BuildVersionData element does not exist in < code > $(BuildVersionXml)</ code > </ td >
575+ </ tr >
576+ < tr >
577+ < td > CSM203</ td >
578+ < td > [Warning] Unexpected attribute on BuildVersionData Element</ td >
579+ </ tr >
580+ < tr >
581+ < td > CSM204</ td >
582+ < td > XML format of file specified by `$(BuildVersionXml)' is invalid</ td >
583+ </ tr >
584+ </ tbody >
585+ </ table >
586+ < hr >
587+ < p > < sup > 1</ sup > CSM106 is essentially an internal sanity test. The props/targets files ensure that
588+ < code > $(CiBuildIndex)</ code > and < code > $(CiBuildName)</ code > have a value unless $(IsReleaseBuild) is set. In that case
589+ the targets file will force them to empty. So, there's no way to test for or hit this condition
590+ without completely replacing/bypassing the props/targets files for the task. Which is obviously,
591+ an unsupported scenario 😁.</ p >
489592
490593</ article >
491594
492595 < div class ="contribution d-print-none ">
493- < a href ="https://github.com/UbiquityDotNET/Llvm.NET /blob/develop/docfx/build-tasks/index.md/#L1 " class ="edit-link "> Edit this page</ a >
596+ < a href ="https://github.com/UbiquityDotNET/CSemVer.GitBuild /blob/develop/docfx/build-tasks/index.md/#L1 " class ="edit-link "> Edit this page</ a >
494597 </ div >
495598
496599 < div class ="next-article d-print-none border-top " id ="nextArticle "> </ div >
0 commit comments