Skip to content

Commit c27cba1

Browse files
smailletsmaillet
authored
Updated readme (#37)
Co-authored-by: smaillet <25911635+smaillet@users.noreply.github.com>
1 parent 79f4192 commit c27cba1

File tree

1 file changed

+13
-109
lines changed

1 file changed

+13
-109
lines changed

‎README.md‎

Lines changed: 13 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1-
# CSemVer.Build.Tasks
2-
Automated Constrained Semantic Versioning for MSBuild projects
1+
# Ubiquity.NET.Versioning
2+
This repo includes automated Constrained Semantic Versioning ([CSemVer](https:/csemver.org))
3+
for MSBuild projects
34

45
![Nuget](https://img.shields.io/nuget/dt/CSemVer.Build.Tasks.svg)
56
![PR/CI Workflow Status](https://img.shields.io/github/actions/workflow/status/UbiquityDotNET/CSemVer.GitBuild/pr-build.yml?label=PR%2FCI%20Build%20Status)
@@ -32,117 +33,20 @@ In particular, local build packages have a higher precedence than CI or release
3233
components of the version match. This ensures that what you are building includes the dependent packages
3334
you just built instead of the last one released publicly.
3435

35-
The following is a list of the version formats in descending order of precedence:
36-
37-
| Build Type | Format |
38-
|------------|--------|
39-
| Local build | `{BuildMajor}.{BuildMinor}.{BuildPatch}--ci-{UTCTIME of build }-ZZZ` |
40-
| Pull Request | `{BuildMajor}.{BuildMinor}.{BuildPatch}--ci-{UTCTIME of PR Commit}-PRQ+{COMMIT ID}` |
41-
| Official CI builds | `{BuildMajor}.{BuildMinor}.{BuildPatch}--ci-{UTCTIME of HEAD Commit}-BLD+{COMMIT ID}` |
42-
| Official PreRelease | `{BuildMajor}.{BuildMinor}.{BuildPatch}-{PreReleaseName}[.PreReleaseNumber][.PreReleaseFix]+{COMMIT ID}` |
43-
| Official Release | `{BuildMajor}.{BuildMinor}.{BuildPatch}+{COMMIT ID}` |
44-
45-
This library provides a single package to automate the generation of these versions in an easy to use
46-
NuGet Package.
47-
48-
The package creates File and Assembly Versions and defines the appropriate MsBuild properties
49-
so the build will automatically incorporate them.
50-
> **NOTE:**
51-
The automatic use of MsBuild properties requires using the new SDK attribute support for .NET projects.
52-
Where the build auto generates the assembly info. If you are using some other means to auto generate the
53-
assembly level versioning attributes. You can use the properties generated by this package to generate the
54-
attributes.
55-
56-
File and AssemblyVersions are computed based on the CSemVer "Ordered version", which
57-
is a 64 bit value that maps to a standard windows FILEVERSION Quad with each part
58-
consuming 16 bits. This ensures a strong relationship between the assembly/file versions
59-
and the packages as well as ensures that CI builds can function properly. Furthermore, this
60-
guarantees that each build has a different file and assembly version so that strong name
61-
signing functions properly to enable loading different versions in the same process.
62-
63-
The Major, Minor and Patch versions are only updated in the master branch at the time
64-
of a release. This ensures the concept that SemVer versions define released products. The
65-
version numbers used are stored in the repository in the BuildVersion.xml
66-
67-
## Properties used to determine the version
68-
CSemVer.Build uses MSBuild properties to determine the final version number.
69-
70-
|Name |Default Value | Description|
71-
|-------------------|--------------------------------------------------------------|------------|
72-
| BuildMajor | Read from BuildVersion.xml | Major portion of the build number |
73-
| BuildMinor | Read from BuildVersion.xml | Minor portion of the build number |
74-
| BuildPatch | Read from BuildVersion.xml | Patch portion of the build number |
75-
| PreReleaseName | `<Undefined>` or value read from BuildVersion.xml if present | PreRelease Name of the CSemVer |
76-
| PreReleaseNumber | `<Undefined>` or value read from BuildVersion.xml if present | PreRelease Number of the CSemVer |
77-
| PreReleaseFix | `<Undefined>` or value read from BuildVersion.xml if present | PreRelease Fix of the CSemVer |
78-
| BuildMeta | `<undefined>` | Build meta for the version
79-
| CiBuildName | `<see notes>` | CSemVer CI name
80-
| CiBuildIndex | ISO 8601 formated UTC time-stamp for the build | Provides a unique build to build value guaranteed to increase with each build
81-
82-
### CiBuildName
83-
Unless explicitly provided, the CiBuildName is determined by a set of properties that indicate the nature of the
84-
build. The properties used (in evaluation order) are:
85-
86-
|Name |Default Value |CiBuildName | Description|
87-
|-------------------|---------------|---------------|------------|
88-
|IsPullRequestBuild | `<Undefined>` |`PRQ` if true | Used to indicate if the build is from a pull request |
89-
|IsAutomatedBuild | `<Undefined>` |`BLD` if true | Used to indicate if the build is an automated build |
90-
|IsReleaseBuild | `<Undefined>` |`ZZZ` if !true | Used to indicate if the build is an official release build |
91-
92-
These three values are determined by the automated build in some form. These are either explicit variables set for
93-
the build definition or determined on the fly based on values set by the build. Commonly a `directory.build.props`
94-
for a repository will specify these. The following is an example for setting them based on an AppVeyor build in
95-
the `Directory.Build.props` file:
96-
97-
``` xml
98-
<PropertyGroup>
99-
<!-- If running in APPVEYOR it is an automated build -->
100-
<IsAutomatedBuild Condition="'$(IsAutomatedBuild)'=='' AND '$(APPVEYOR)'!=''">true</IsAutomatedBuild>
101-
<IsAutomatedBuild Condition="'$(IsAutomatedBuild)'==''">false</IsAutomatedBuild>
102-
103-
<!-- If it has a PR number associated it is a PR build -->
104-
<IsPullRequestBuild Condition="'$(IsPullRequestBuild)'=='' AND '$(APPVEYOR_PULL_REQUEST_NUMBER)'!=''">true</IsPullRequestBuild>
105-
<IsPullRequestBuild Condition="'$(IsPullRequestBuild)'==''">false</IsPullRequestBuild>
106-
107-
<!-- Tags applied without a PR are release builds -->
108-
<IsReleaseBuild Condition="'$(IsReleaseBuild)'=='' AND '$(APPVEYOR_REPO_TAG)'=='true' AND '$(APPVEYOR_PULL_REQUEST_NUMBER)'==''">true</IsReleaseBuild>
109-
<IsReleaseBuild Condition="'$(IsReleaseBuild)'==''">false</IsReleaseBuild>
110-
</PropertyGroup>
111-
```
112-
113-
## BuildVersion.xml
114-
If the MSBuild property `BuildMajor` is not set, then the base build version is read from the
115-
repository file specified in the BuildVersion.xml, typically this is located at the root of a
116-
repository so that any child projects share the same versioning information. The location of the
117-
file is specified by an MSBuild property `BuildVersionXml`. The contents of the file are fairly
118-
simple and only requires a single `BuildVersionData` element with a set of attributes. The
119-
available attributes are:
120-
121-
|Name |Description|
122-
|-------------------|-----------|
123-
| BuildMajor | Major portion of the build number |
124-
| BuildMinor | Minor portion of the build number |
125-
| BuildPatch | Patch portion of the build number |
126-
| PreReleaseName | PreRelease Name of the CSemVer |
127-
| PreReleaseNumber | PreRelease Number of the CSemVer |
128-
| PreReleaseFix | PreRelease Fix of the CSemVer |
129-
130-
Only the Major, minor and Patch numbers are required.
131-
132-
### Example BuildVersion.XML
133-
``` xml
134-
<BuildVersionData
135-
BuildMajor = "5"
136-
BuildMinor = "0"
137-
BuildPatch = "0"
138-
PreReleaseName = "alpha"
139-
/>
140-
```
141-
This will set the build version to `5.0.0-alpha` for all projects in the repository
36+
## Documentation
37+
Full documentation on the tasks is available in the project's [docs site](https://ubiquitydotnet.github.io/CSemVer.GitBuild/)
14238

14339
## Building the tasks
14440
The build uses a common PowerShell module pattern for Ubiquity.NET projects. To build the sources
14541
use the `Build-All.ps1` script. You can also open the `src/Ubiquity.NET.Versioning.slnx` in any
14642
editor/IDE that has support for the slnx solution format. (Visual Studio 2022 is used but other
14743
options may work, though they are not supported. If you have experience then PRs are welcome for
14844
additional support - but such PRs ***MUST NOT*** break the VS support.)
45+
46+
>[!IMPORTANT]
47+
> It is important to note that IDE builds of a clean repo get will FAIL! This is due to the
48+
> mechanisms used to eliminate circular dependencies while still supporting automated versioning
49+
> of the projects themselves. To resolve this, you must run the `.\New-GeneratedVersionProps.ps1`
50+
> at least once to create the imported `generatedversion.props` file. This is also generated by
51+
> the `Build-All.ps1` script, which is the recommended means of generated the required file. This
52+
> is only needed the first time (or any time the `buildversion.xml` changes).

0 commit comments

Comments
 (0)