This document covers the basic versioning strategy and which properties to use. It is based on the rules outlined in our Azure SDK Releases doc and it closely matches the .NET versioning rules but simplified to only include the parts necessary for our libraries.
Package version will look like:
MAJOR.MINOR.PATCH-PRERELEASE
In the project file use the Version
property to define the MAJOR.MINOR.PATCH-preview.X
part of the version.
<Version>1.0.0-preview.1</Version>
By default builds will replace any prerelease identifier with a dev.yyyyMMdd.r
to ensure we have unique package versions. The date will come from either
today's date or a property named OfficialBuildId
which we will pass as part of our build pipelines.
If we need to produce a package that is not a dev version and has the version in the project (i.e. stable or preview) then the SkipDevBuildNumber
should
be passed as true
to the packaging command.
See Incrementing after release for general guidance but at a high level we will do the following versioning changes:
- After a preview release we bump the number after the preview.
1.0.0-preview.1
->1.0.0-preview.2
- After a GA release we bump the minor version and switch to preview 1.
1.0.0
->1.1.0-preview.1
- Prior to a hot-fix release we bump the patch version.
1.0.0
->1.0.1
Versions are automatically bumped up in package project .csproj
files as well as package changelog CHANGELOG.md
as part of the release process. To increment a version locally make use of the eng\scripts\Update-PkgVersion.ps1
script.
By default the assembly version will be set to the Version
property but if the assembly version needs to be different for some reason then it can be independently set by the AssemblyVersion
property.
File version has 4 parts and needs to increase every official build. This is especially important when building MSIs.
They will use the following format which is also used by the .NET team:
FILEMAJOR.FILEMINOR.FILEPATCH.FILEREVISION
FILEMAJOR
: Specified in the first part ofVersionPrefix
property.FILEMINOR
: Set toMINOR * 100 + PATCH / 100
, whereMINOR
andPATCH
are the 2nd and 3rd parts ofVersionPrefix
property.FILEPATCH
: Set to(PATCH % 100) * 100 + yy
.FILEREVISION
: Set to(50 * mm + dd) * 100 + r
. This algorithm makes it easy to parse the month and date fromFILEREVISION
while staying in the range of a short which is what a version element uses.
The versioning scheme imposes the following limits on these version parts:
MAJOR
version is in range [0-65535]MINOR
version is in range [0-654]PATCH
version is in range [0-9999]
Parameter | Description |
---|---|
OfficialBuildId | ID of current build. The accepted format is yyyyMMdd.r . Should be passed to build in YAML official build defintion. |