Better document ranges with prerelease (#3281)

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).

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

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. `<version>1.0.0-pre</version>`. 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.