From 57792faaad571ffd6f1622a6754a2328d656abda Mon Sep 17 00:00:00 2001 From: Nikolche Kolev Date: Tue, 30 Apr 2024 10:29:56 -0700 Subject: [PATCH] Better document ranges with prerelease (#3281) --- docs/concepts/Dependency-Resolution.md | 20 ++++++++++++++++++++ docs/concepts/Package-Versioning.md | 2 ++ docs/reference/errors-and-warnings/NU5104.md | 2 ++ 3 files changed, 24 insertions(+) diff --git a/docs/concepts/Dependency-Resolution.md b/docs/concepts/Dependency-Resolution.md index 88cb3fae3..0f7da2b60 100644 --- a/docs/concepts/Dependency-Resolution.md +++ b/docs/concepts/Dependency-Resolution.md @@ -112,6 +112,21 @@ In some cases, it's not possible to meet all version requirements. As shown belo In these situations, the top-level consumer (the application or package) should add its own direct dependency on Package B so that the [Direct dependency wins](#direct-dependency-wins) rule applies. +### Version ranges and prerelease versions with PackageReference + +It is not unusual for a package to have both stable and prerelease versions available. +When resolving a dependency graph, NuGet decides whether to consider prerelease versions for a package based on a single rule: +`If the project or any packages within the graph request a prerelease version of a package, then include both prerelease or stable versions, otherwise consider stable versions only.` + +In practice, under the lowest applicable rule, this means: + +| Version Range | Available versions | Selected version | +|---------------|--------------------|------------------| +| [1.0.0, 2.0.0) | 1.2.0-beta.1, 1.2.0, | 1.2.0 | +| [1.0.0, 2.0.0-0) | 1.2.0-beta.1, 1.2.0, | 1.2.0-beta.1 | +| [1.0.0, 2.0.0) | 1.2.0-beta.1, 2.0.0-beta.3 | None, [NU1103](../reference/errors-and-warnings/NU1103.md) is raised. | +| [1.0.0, 2.0.0-rc) | 1.2.0-beta.1, 2.0.0-beta.3 | 1.2.0-beta.1 | + ## Dependency resolution with packages.config With `packages.config`, a project's dependencies are written to `packages.config` as a flat list. Any dependencies of those packages are also written in the same list. When packages are installed, NuGet might also modify the `.csproj` file, `app.config`, `web.config`, and other individual files. @@ -122,6 +137,11 @@ By default, NuGet 2.8 looks for the lowest patch version (see [NuGet 2.8 release The `packages.config` process for resolving dependencies gets complicated for larger dependency graphs. Each new package installation requires a traversal of the whole graph and raises the chance for version conflicts. When a conflict occurs, installation is stopped, leaving the project in an indeterminate state, especially with potential modifications to the project file itself. This is not an issue when using other package management formats. +### Version ranges and prerelease versions with packages.config + +packages.config resolution does not allow mixing of stable and pre-release dependency in a graph. +If a dependency is expressed with a range like `[1.0.0, 2.0.0)`, pre-release packages are not allowed in the graph. + ## Managing dependency assets When using the PackageReference format, you can control which assets from dependencies flow into the top-level project. For details, see [PackageReference](../consume-packages/package-references-in-project-files.md#controlling-dependency-assets). diff --git a/docs/concepts/Package-Versioning.md b/docs/concepts/Package-Versioning.md index 9fb2ce6e1..01a806a88 100644 --- a/docs/concepts/Package-Versioning.md +++ b/docs/concepts/Package-Versioning.md @@ -95,6 +95,8 @@ Note that versions such as `1.0.1-rc.10` and `1.0.1-rc.2` are not parsable by ol 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. This recommendation only applies this schema. +Despite the ordering shown above, NuGet does not always consider both stable & prerelease packages during dependency resolution. Those rules are detailed in [Dependency Resolution](./Dependency-Resolution.md). + --- ## Version ranges diff --git a/docs/reference/errors-and-warnings/NU5104.md b/docs/reference/errors-and-warnings/NU5104.md index 860b0d909..2fad138bb 100644 --- a/docs/reference/errors-and-warnings/NU5104.md +++ b/docs/reference/errors-and-warnings/NU5104.md @@ -22,3 +22,5 @@ The project or nuspec being packaged contains a dependency on a prerelease packa If you intend to create a prerelease package then please refer to SemVer2 guidelines and add a prerelease tag to the version property i.e. `1.0.0-pre`. If you intend to create a stable package then please update the specified dependency version to a stable version. +> [!NOTE] +> Mixing stable and prerelease packages may lead to unexpected behaviors are resolution time. Learn more about how [PackageReference](../../concepts/Dependency-Resolution.md#version-ranges-and-prerelease-versions-with-packagereference) and [packages.config](../../concepts/Dependency-Resolution.md#version-ranges-and-prerelease-versions-with-packagesconfig) projects handle this resolution.