Skip to content

Commit fdc55f5

Browse files
nkolev92nkolev92
authored
Refactoring Package Versioning, add tabs for SemVer 1.0 vs SemVer 2.0. (#3190)
1 parent 339fa57 commit fdc55f5

File tree

3 files changed

+65
-84
lines changed

3 files changed

+65
-84
lines changed

‎docs/concepts/Dependency-Resolution.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,8 +57,16 @@ When using a floating version, NuGet resolves the highest version of a package t
5757

5858
![Choosing version 6.0.1 when a floating version 6.0.* is requested](media/floating-versions-1.png)
5959

60+
| Version | Versions present on server | Resolution | Reason | Notes |
61+
|----------|--------------|-------------|-------------|-------------|
62+
| * | 1.1.0 <br> 1.1.1 <br> 1.2.0 <br> 1.3.0-alpha | 1.2.0 | The highest stable version. |
63+
| 1.1.* | 1.1.0 <br> 1.1.1 <br> 1.1.2-alpha <br> 1.2.0-alpha | 1.1.1 | The highest stable version that respects the specified pattern.|
64+
| \*-\* | 1.1.0 <br> 1.1.1 <br> 1.1.2-alpha <br> 1.3.0-beta | 1.3.0-beta | The highest version including the not stable versions. | Available in Visual Studio version 16.6, NuGet version 5.6, .NET Core SDK version 3.1.300 |
65+
| 1.1.\*-\* | 1.1.0 <br> 1.1.1 <br> 1.1.2-alpha <br> 1.1.2-beta <br> 1.3.0-beta | 1.1.2-beta | The highest version respecting the pattern and including the not stable versions. | Available in Visual Studio version 16.6, NuGet version 5.6, .NET Core SDK version 3.1.300 |
66+
6067
> [!Note]
61-
> For information on the behavior of floating versions and pre-release versions, see [Package versioning](package-versioning.md#version-ranges).
68+
> Floating version resolution does not take into account whether or not a package is listed.
69+
> Floating version resolution will be resolved locally if the conditions can be satisfied with packages in the Global Package Folder.
6270
6371
#### Direct dependency wins
6472

‎docs/concepts/Package-Versioning.md

Lines changed: 55 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,15 @@ A specific package is always referred to using its package identifier and an exa
1414

1515
When creating a package, you assign a specific version number with an optional pre-release text suffix. When consuming packages, on the other hand, you can specify either an exact version number or a range of acceptable versions.
1616

17+
The following document follows the [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) standard, supported by NuGet 4.3.0+ and Visual Studio 2017 version 15.3+.
18+
Certain [semantics of SemVer v2.0.0](#semantic-versioning-200) are not supported in older clients.
19+
1720
In this topic:
1821

1922
- [Version basics](#version-basics) including pre-release suffixes.
2023
- [Version ranges](#version-ranges)
2124
- [Normalized version numbers](#normalized-version-numbers)
25+
- [Semantic Versioning 2.0.0](#semantic-versioning-200)
2226

2327
## Version basics
2428

@@ -27,7 +31,7 @@ A specific version number is in the form *Major.Minor.Patch[-Suffix]*, where the
2731
- *Major*: Breaking changes
2832
- *Minor*: New features, but backwards compatible
2933
- *Patch*: Backwards compatible bug fixes only
30-
- *-Suffix* (optional): a hyphen followed by a string denoting a pre-release version (following the [Semantic Versioning or SemVer 1.0 convention](https://semver.org/spec/v1.0.0.html)).
34+
- *-Suffix* (optional): a hyphen followed by a string denoting a pre-release version (following the [Semantic Versioning or SemVer](https://semver.org/) convention).
3135

3236
**Examples:**
3337

@@ -51,10 +55,12 @@ That said, package developers generally follow recognized naming conventions:
5155
- `-beta`: Beta release, typically one that is feature complete for the next planned release, but may contain known bugs.
5256
- `-rc`: Release candidate, typically a release that's potentially final (stable) unless significant bugs emerge.
5357

58+
When ordering versions by precedence, NuGet follows the SemVer standard and chooses a version without a suffix first, then applies precedence to pre-release versions in reverse alphabetical order and treats dot notation numbers with numerical order.
59+
5460
> [!Note]
55-
> NuGet 4.3.0+ supports [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html), which supports pre-release numbers with dot notation, as in *1.0.1-build.23*. Dot notation is not supported with NuGet versions before 4.3.0. You can use a form like *1.0.1-build23*. It is recommended to use NuGet 4.3.0+, because nuget.org and newer NuGet clients will not treat "1.0.1-build23" as greater than "1.0.1-build3".
61+
> Prerelease numbers with dot notation, as in *1.0.1-build.23*, are considered are part of the [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html) standard, and as such are [only supported with NuGet 4.3.0+](#semantic-versioning-200).
5662
57-
When resolving package references and multiple package versions differ only by suffix, NuGet chooses a version without a suffix first, then applies precedence to pre-release versions in reverse alphabetical order and treats dot notation numbers with numerical order. For example, the following versions would be chosen in the exact order shown:
63+
### [SemVer 2.0 sorting](#tab/semver20sort)
5864

5965
```
6066
1.0.1
@@ -68,37 +74,28 @@ When resolving package references and multiple package versions differ only by s
6874
1.0.1-aaa
6975
```
7076

71-
Note that, 1.0.1-alpha10 is sorted strictly in reverse alphabetical order, whereas 1.0.1-rc.10 is greater precedence than 1.0.1-rc.2.
72-
73-
## Semantic Versioning 2.0.0
74-
75-
With NuGet 4.3.0+ and Visual Studio 2017 version 15.3+, NuGet supports [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
77+
Note that 1.0.1-alpha10 is sorted strictly in reverse alphabetical order, whereas 1.0.1-rc.10 is greater precedence than 1.0.1-rc.2.
7678

77-
Certain semantics of SemVer v2.0.0 are not supported in older clients. NuGet considers a package version to be SemVer v2.0.0 specific if either of the following statements is true:
79+
### [SemVer 1.0 sorting](#tab/semver10sort)
7880

79-
- The pre-release label is dot-separated, for example, *1.0.0-alpha.1*
80-
- The version has build-metadata, for example, *1.0.0+githash*
81-
82-
For nuget.org, a package is defined as a SemVer v2.0.0 package if either of the following statements is true:
83-
84-
- The package's own version is SemVer v2.0.0 compliant but not SemVer v1.0.0 compliant, as defined above.
85-
- Any of the package's dependency version ranges has a minimum or maximum version that is SemVer v2.0.0 compliant but not SemVer v1.0.0 compliant, defined above; for example, *[1.0.0-alpha.1, )*.
86-
87-
If you upload a SemVer v2.0.0-specific package to nuget.org, the package is invisible to older clients and available to only the following NuGet clients:
88-
89-
- NuGet 4.3.0+
90-
- Visual Studio 2017 version 15.3+
91-
- Visual Studio 2015 with [NuGet VSIX v3.6.0](https://dist.nuget.org/visualstudio-2015-vsix/latest/NuGet.Tools.vsix)
92-
- dotnet
93-
- dotnetcore.exe (.NET SDK 2.0.0+)
81+
```
82+
1.0.1
83+
1.0.1-zzz
84+
1.0.1-open
85+
1.0.1-beta05
86+
1.0.1-beta02
87+
1.0.1-beta
88+
1.0.1-alpha2
89+
1.0.1-alpha10
90+
1.0.1-aaa
91+
```
9492

95-
Third-party clients:
93+
Note that versions such as `1.0.1-rc.10` and `1.0.1-rc.2` are not parsable by older versions of the client, and such packages with those versions won't be available for download with those clients.
9694

97-
- JetBrains Rider
98-
- Paket version 5.0+
95+
If you use numerical suffixes with pre-release tags that might use double-digit numbers (or more), use leading zeroes as in beta01 and beta05 to ensure that they sort correctly when the numbers get larger.
96+
This recommendation only applies this schema.
9997

100-
<!-- For compatibility with previous dependency-versions page -->
101-
<a name="version-ranges"></a>
98+
---
10299

103100
## Version ranges
104101

@@ -117,11 +114,6 @@ When referring to package dependencies, NuGet supports using interval notation f
117114
| [1.0,2.0) | 1.0 ≤ x < 2.0 | Mixed inclusive minimum and exclusive maximum version |
118115
| (1.0) | invalid | invalid |
119116

120-
When using the PackageReference format, NuGet also supports using a floating notation, \*, for Major, Minor, Patch, and pre-release suffix parts of the number. Floating versions are not supported with the `packages.config` format. When a floating version is specified, the rule is to resolve to the highest existent version that matches the version description. Examples of floating versions and the resolutions are below.
121-
122-
> [!Note]
123-
> Version ranges in PackageReference include pre-release versions. By design, floating versions do not resolve prerelease versions unless opted into. For the status of the related feature request, see [issue 6434](https://github.com/NuGet/Home/issues/6434#issuecomment-358782297).
124-
125117
### Examples
126118

127119
Always specify a version or version range for package dependencies in project files, `packages.config` files, and `.nuspec` files. Without a version or version range, NuGet 2.8.x and earlier chooses the latest available package version when resolving a dependency, whereas NuGet 3.x and later chooses the lowest package version. Specifying a version or version range avoids this uncertainty.
@@ -158,19 +150,6 @@ Always specify a version or version range for package dependencies in project fi
158150
<PackageReference Include="ExamplePackage" Version="[1.3.2,1.5)" />
159151
```
160152

161-
#### Floating version resolutions
162-
163-
| Version | Versions present on server | Resolution | Reason | Notes |
164-
|----------|--------------|-------------|-------------|-------------|
165-
| * | 1.1.0 <br> 1.1.1 <br> 1.2.0 <br> 1.3.0-alpha | 1.2.0 | The highest stable version. |
166-
| 1.1.* | 1.1.0 <br> 1.1.1 <br> 1.1.2-alpha <br> 1.2.0-alpha | 1.1.1 | The highest stable version that respects the specified pattern.|
167-
| \*-\* | 1.1.0 <br> 1.1.1 <br> 1.1.2-alpha <br> 1.3.0-beta | 1.3.0-beta | The highest version including the not stable versions. | Available in Visual Studio version 16.6, NuGet version 5.6, .NET Core SDK version 3.1.300 |
168-
| 1.1.\*-\* | 1.1.0 <br> 1.1.1 <br> 1.1.2-alpha <br> 1.1.2-beta <br> 1.3.0-beta | 1.1.2-beta | The highest version respecting the pattern and including the not stable versions. | Available in Visual Studio version 16.6, NuGet version 5.6, .NET Core SDK version 3.1.300 |
169-
170-
> [!Note]
171-
> Floating version resolution does not take into account whether or not a package is listed.
172-
> Floating version resolution will be resolved locally if the conditions can be satisfied with packages in the Global Package Folder.
173-
174153
**References in `packages.config`:**
175154

176155
In `packages.config`, every dependency is listed with an exact `version` attribute that's used when restoring packages. The `allowedVersions` attribute is used only during update operations to constrain the versions to which the package might be updated.
@@ -229,7 +208,7 @@ The `version` attribute in a `<dependency>` element describes the range versions
229208
## Normalized version numbers
230209

231210
> [!Note]
232-
> This is a breaking change for NuGet 3.4 and later.
211+
> This is a breaking change for NuGet 3.4+.
233212
234213
When obtaining packages from a repository during install, reinstall, or restore operations, NuGet 3.4+ treats version numbers as follows:
235214

@@ -249,6 +228,34 @@ When obtaining packages from a repository during install, reinstall, or restore
249228

250229
However, NuGet package repositories must treat these values in the same way as NuGet to prevent package version duplication. Thus a repository that contains version *1.0* of a package should not also host version *1.0.0* as a separate and different package.
251230

231+
## Semantic Versioning 2.0.0
232+
233+
Certain semantics of SemVer v2.0.0 are not supported in older clients.
234+
NuGet considers a package version to be SemVer v2.0.0 specific if either of the following statements is true:
235+
236+
- The pre-release label is dot-separated, for example, *1.0.0-alpha.1*
237+
- The version has build-metadata, for example, *1.0.0+githash*
238+
239+
For nuget.org, a package is defined as a SemVer v2.0.0 package if either of the following statements is true:
240+
241+
- The package's own version is SemVer v2.0.0 compliant but not SemVer v1.0.0 compliant, as defined above.
242+
- Any of the package's dependency version ranges has a minimum or maximum version that is SemVer v2.0.0 compliant but not SemVer v1.0.0 compliant, defined above; for example, *[1.0.0-alpha.1, )*.
243+
244+
If you upload a SemVer v2.0.0-specific package to nuget.org, the package is invisible to older clients and available to only the following NuGet clients:
245+
246+
- NuGet 4.3.0+
247+
- Visual Studio 2017 version 15.3+
248+
- Visual Studio 2015 with [NuGet VSIX v3.6.0](https://dist.nuget.org/visualstudio-2015-vsix/latest/NuGet.Tools.vsix)
249+
- .NET SDK 2.0.0+
250+
251+
Third-party clients:
252+
253+
- JetBrains Rider
254+
- Paket version 5.0+
255+
256+
<!-- For compatibility with previous dependency-versions page -->
257+
<a name="version-ranges"></a>
258+
252259
## Where NuGetVersion diverges from Semantic Versioning
253260

254261
If you want to programatically use NuGet package versions, it is strongly recommended to use [the package NuGet.Versioning](https://www.nuget.org/packages/NuGet.Versioning). The static method `NuGetVersion.Parse(string)` can be used to parse the version strings, and `VersionComparer` can be used to sort `NuGetVersion` instances.

‎docs/create-packages/Prerelease-Packages.md

Lines changed: 1 addition & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -52,38 +52,4 @@ By default, NuGet does not include pre-release versions when working with packag
5252
## Semantic versioning
5353

5454
The [Semantic Versioning or SemVer convention](https://semver.org/spec/v1.0.0.html) describes how to utilize strings in version numbers to convey the meaning of the underlying code.
55-
56-
In this convention, each version has three parts, `Major.Minor.Patch`, with the following meaning:
57-
58-
- `Major`: Breaking changes
59-
- `Minor`: New features, but backwards compatible
60-
- `Patch`: Backwards compatible bug fixes only
61-
62-
Pre-release versions are then denoted by appending a hyphen and a string after the patch number. Technically speaking, you can use *any* string after the hyphen and NuGet will treat the package as pre-release. NuGet then displays the full version number in the applicable UI, leaving consumers to interpret the meaning for themselves.
63-
64-
With this in mind, it's generally good to follow recognized naming conventions such as the following:
65-
66-
- `-alpha`: Alpha release, typically used for work-in-progress and experimentation
67-
- `-beta`: Beta release, typically one that is feature complete for the next planned release, but may contain known bugs.
68-
- `-rc`: Release candidate, typically a release that's potentially final (stable) unless significant bugs emerge.
69-
70-
> [!Note]
71-
> NuGet 4.3.0+ supports [Semantic Versioning v2.0.0](https://semver.org/spec/v2.0.0.html), which supports pre-release numbers with dot notation, as in `1.0.1-build.23`. Dot notation is not supported with NuGet versions before 4.3.0. In earlier versions of NuGet, you could use a form like `1.0.1-build23` but this was always considered a pre-release version.
72-
73-
Whatever suffixes you use, however, NuGet will give them precedence in reverse alphabetical order:
74-
75-
```
76-
1.0.1
77-
1.0.1-zzz
78-
1.0.1-rc
79-
1.0.1-open
80-
1.0.1-beta.12
81-
1.0.1-beta.5
82-
1.0.1-beta
83-
1.0.1-alpha.2
84-
1.0.1-alpha
85-
```
86-
87-
As shown, the version without any suffix will always take precedence over pre-release versions.
88-
89-
Leading 0s are not needed with semver2, but they are with the old version schema. If you use numerical suffixes with pre-release tags that might use double-digit numbers (or more), use leading zeroes as in beta.01 and beta.05 to ensure that they sort correctly when the numbers get larger. This recommendation only applies to the old version schema.
55+
[Learn more](../concepts/Package-Versioning.md) about the package versioning basics.

0 commit comments

Comments
 (0)