NU1608 warning is not evaluating prerelease versions combined with exclusive upper bounds properly

[bording]

The NU1608 warning that was added in NuGet/NuGet.Client#1678 that displays when a package is outside of a dependency constraint is not working correctly when prerelease versions are combined with exclusive upper bounds.

The scenario:

• PackageA version 1.0.0 has a dependency on PackageB defined as [1.0.0, 2.0.0)
• The following versions of PackageB exist: 1.0.0, 2.0.0-beta1, 2.0.0
• A project has the following package references:
  • <PackageReference Include="PackageA" Version="1.0.0" />
  • <PackageReference Include="PackageB" Version="2.0.0" />

In this case, an NU1608 warning is displayed as expected.

However, if the project's package references are instead:

• <PackageReference Include="PackageA" Version="1.0.0" />
• <PackageReference Include="PackageB" Version="2.0.0-beta1" />

No warning is displayed.

Given that PackageA's constraint on PackageB is [1.0.0, 2.0.0), any package with a major version > 1 should fall outside of that version range constraint, regardless if it's a prerelease package or not.

Based on that, referencing PackageB 2.0.0-beta1 should also cause an NU1608 warning.

NuGet product used: VS UI
VS version: 2017 15.5.3

cc: @adamralph

[nkolev92]

I think what it's doing is correct.
2.0.0 > 2.0.0-beta1...so that puts beta1 in the range.

//cc
@emgarten

[bording]

I think what it's doing is correct.
2.0.0 > 2.0.0-beta1...so that puts beta1 in the range.

When you consider the reason for putting an upper bound on a version range, I totally disagree.

If you're following SemVer, you're trying to avoid breaking changes. Picking up a prerelease version of a new major completely defeats the point of putting the upper bound there.

Moving to version 2 of PackageB means I have breaking changes. That means that that 2.0.0-beta1 also has breaking changes.

If I've declared that PackageA does not work with 2.0 of PackageB, then I want consumers of PackageA to see a warning letting them know that they're violating the constraint.

[nkolev92]

SemVer only declares the ordering.

As I mentioned earlier, so 2.0.0 > 2.0.0.-beta1
https://semver.org/#spec-item-11

So the way NuGet implements the ranges is correct.
It's not intuitive but semver compliant.

The way to go here would be something like marking the upper bound as "2.0.0-0" as that'd be the lowest possible prerelease version of 2.0.0. @emgarten can correct me if I'm wrong here.

[nkolev92]

Basically, think of it this way.

1.0.0 < 2.0.0-beta1 <2.0.0

And you're saying 1.0.0 and higher works, and lower than 2.0.0 works

[bording]

The way to go here would be something like marking the upper bound as "2.0.0-" as that'd be the lowest possible prerelease version of 2.0.0. @emgarten can correct me if I'm wrong here.

Setting the range to [1.0.0, 2.0.0-) in my PackageB project to get to try to get the package to build with that dependency does not work:

C:\Program Files\dotnet\sdk\2.1.4\NuGet.targets(103,5): error : '[1.0.0, 2.0.0-)' is not a valid version string. 

Basically, think of it this way.

1.0.0 < 2.0.0-beta1 <2.0.0

And you're saying 1.0.0 and higher works, and lower than 2.0.0 works

While I understand what you're saying, and from a general sorting order you are correct, I feel like falling back on that to explain this behavior is largely missing the point of what specifying version ranges is for.

If I was specifying an inclusive upper bound, then I totally think that prerelease versions of 2.0.0 should be included. But if I've specified an exclusive upper bound, then I'm declaring that the major version of the package should never be 2.

[emgarten]

2.0.0-0 would be the lowest valid pre-release version.

I get that this is confusing since you intend to limit the version to 1.x.

Ranges in NuGet have always worked this way and I think it would be a major breaking change to the most basic part of NuGet to change this behavior. I am not sure that this could or should be changed.

[bording]

Ranges in NuGet have always worked this way and I think it would be a major breaking change to the most basic part of NuGet to change this behavior. I am not sure that this could or should be changed.

Then that means there are a whole bunch of people out there handling version ranges on packages incorrectly. I suspect this behavior would be quite the surprise to most people, in fact.

I totally get the whole "can't make breaking changes" thing, but this definitely feels like a bug.

At least the 2.0.0-0 workaround appears to work. Is that guaranteed to block all prerelease versions?

[nkolev92]

I disagree with saying that this is a bug.
That's just how SemVer is, and NuGet is SemVer compliant.

It's definitely not the most intuitive thing, I agree, but having a value (2.0.0-beta1) mean one thing as an exact version, but another thing in a version range will be even more confusing.

[SimonCropp]

may "technically" not be a bug. but it is so outside the majority of peoples understanding and usage that it should change.

[abatishchev]

So without changing anything in the existing behavior, how to specify 2.x) where 2.x is either release, prerelease, anything? In other words "no packages from the 2.x branch can be used" (including 2.0-rc-final, surprise!).

[adamralph]

I think this may be a regression. IIRC, earlier versions of NuGet (before <PackageReference>) did exhibit the desired behaviour, i.e. [1.0.0, 2.0.0) would exclude any 2.0.0 pre-release versions. I was involved in a discussion a few years ago about this very topic, and I'm all but certain it was agreed to implement to exclusive upper bounds in that way. Unfortunately I can't find the conversation (it may be hidden away somewhere in codeplex).

But more importantly, that is the desired behaviour. No-one will ever want to specify "use any 1.x versions, but no 2.x versions, unless they are pre-release". That scenario is plain silly.

Note that this is not a conversation about SemVer. SemVer is doing it's own thing and communicating the version info correctly. This is about how to use SemVer compliant version numbers in the context of version ranges, and the only sensible thing to do is to exclude any pre-release versions of the exclusive upper bound.

[mauroservienti]

Nuget documentation states:

Pre-release versions are not included when resolving version ranges. Pre-release versions are included when using a wildcard (*). The version range [1.0,2.0], for example, does not include 2.0-beta, but the wildcard notation 2.0-* does. See issue 912 for further discussion on pre-release wildcards.

That to me means that this is a bug.

[kbaley]

SemVer talks about ordering but I don't think it talks specifically about how to implement ranges. I.e. it says 2.0.0-beta1 < 2.0.0 but it doesn't say something like [1.0.0, 2.0.0) should be defined as 1.0.0 <= x < 2.0.0. That's Nuget's implementation of a specific syntax, isn't it?

For reference, npm has special handling of pre-releases: https://docs.npmjs.com/misc/semver

[rrelyea]

@nkolev92 and I talked this through.
I'm interested to know if @adamralph is right about a regression.

I also told him that I'd like to understand how we treat a few cases:
given that with [1.0.0, 2.0.0) with 2.0.0-b1 in the feeds, will take 2.0.0-b1 w/ no warning.
I'm interested to know what we do with: [1.0.0,2.0.0) with 2.0.0-b1 and 2.0.0 in the feeds.

@nkolev92 will try to squeeze some more investigation/analysis to this sprint or soon thereafter.

[emgarten]

I did some digging on this. At a low level VersionRange/VersionSpec behavior has never changed, [1.0.0, 2.0.0) has always allowed 2.0.0-alpha and I've verified this all the way back to NuGet 2.2.0

What has changed is that stable packages now allow pre-release dependencies in some additional scenarios. Here is an example:

1. A 1.0.0 -> B [1.0.0, 2.0.0)
2. A 1.0.0-alpha -> B [1.0.0, 2.0.0)

For packages.config scenario one does not allow 2.0.0-alpha, purely because it doesn't allow any pre-release packages in the graph by default since A 1.0.0 is stable.

In scenario two when the parent package is pre-release, or if the user opts in to pre-release packages, or if a higher level package is being installed that is pre-release then pre-release is allowed everywhere and 2.0.0-alpha will be added.

Example of this in NuGet 2.2.0:

nuget.2.2.0.exe install a -Output D:\tmp\versiontest\output\ -Source d:\tmp\versiontest\source -Pre
Attempting to resolve dependency 'b (≥ 1.0.0 && < 2.0.0)'.
Successfully installed 'b 2.0.0-alpha'.
Successfully installed 'a 1.0.0'.

For PackageReference stable packages have always been able to resolve pre-release dependencies by default. Which is likely the source of confusion here around how this works and what is allowed.

History on allowing pre-release dependencies

• DNU originally allowed stable packages to depend on pre-release packages. We attempted to remove this but it was a breaking changes for packages that had already shipped as stable that depended on pre-release packages.
• There was a long period of time where System.* packages were pre-release only, making it very hard to ship anything without pre-release versions.
• Pack originally enforced that stable packages depend on only stable packages, but this check was removed after community feedback to make things easier. See: NuGet pack should not fail for release packages with prerelease development dependency #1365

packages.config

• Due to allowing NuGet pack should not fail for release packages with prerelease development dependency #1365 users have been asking for packages.config to also allow stable packages to bring in pre-release dependencies. See: Unable to install package with stable version but prerelease dependencies #2944 and Installing a non-prerelease package using pre-release dependencies fails installation when packages.config is used, yet installs when PackageReference is used. #6196 This change will probably be made in the future since it is painful for packages.config to work differently from PackageReference, but it will make the issue here worse.

Summary

This is very painful, but I do not see this as a regression. Since version ranges have always worked this way in NuGet changing it would be a major breaking change.

A better way to expression version ranges would be to put them in terms of the lower bound only like npm. Example: ^1.0.0 instead of having to write in < 2.0.0. This would however break older clients that did not understand the syntax.

[abatishchev]

This is very painful, but I do not see this as a regression

Does this mean that the implementation was always different from the documentation?

[emgarten]

The documentation mentioned by @mauroservienti was a recent addition meant to explain that 1.* does not include 1.1.0-beta since there have been a lot of questions on around this. It is incorrect and will be updated.

[304NotModified]

At least the 2.0.0-0 workaround appears to work.

Please add this to the docs until this issue is proper resolved!

[304NotModified]

it looks like the -0 trick is not accepted by nuget.org? :(

(publish from AppVeyor) - https://ci.appveyor.com/project/nlog/nlog-framework-logging/build/1.0.634

Deploying using NuGet provider
Publishing NLog.Extensions.Logging.1.0.1.nupkg to https://www.nuget.org/api/v2/package...
Error publishing package. NuGet server returned 400: The NuGet package contains an invalid .nuspec file. The errors encountered were: 'The package manifest contains an invalid Version: '5.0.0-0'', 'The package manifest contains an invalid Version: '5.0.0-0'', 'The package manifest contains an invalid Version: '5.0.0-0'', 'The package manifest contains an invalid Version: '5.0.0-0'', 'The package manifest contains an invalid Version: '5.0.0-0''. Correct the errors and try again.

[shuebner]

Since even the official documentation now links to this old issue, I will amend the workaround proposed here.

Specifying an open range like [2.1.0, 3.0.0-0) will trigger NU5104 because a pre-release version is mentioned.
The check is not smart enough to figure out that the range does not include a pre-release version.
I created an issue about this here, because the workaround is now basically semi-official and we should not have to pile workaround upon workaround to get sane behavior.

But for now, we have to.
To squelch the warning, you need to add a NoWarn="NU5104" attribute to your PackageReference:

<PackageVersion Include="Abc" Version="[2.0.0, 3.0.0-0)" NoWarn="NU5104" />

When using central package management, the NoWarn cannot be put on the PackageVersion item.
This means that the version range will be in a different place, probably even a different file, from the actual reference and thus the NoWarn, which is not ideal.
Also, the NoWarn must be set for every project actually referencing the dependency.
At this point, specifying Version="[2.0.0, 2.999.999.999]" instead may be ugly, but still "good enough" and will avoid the NU5104 issues.

[shuebner]

NOTE: I noticed this works in VS, but not with dotnet CLI. I will update this comment as soon as I find out why and fix it.

And again for future readers: I ended up adding a target in my root Directory.Build.targets file that restricts all direct package dependencies to their current major version.

This is the main part:

<Target Name="__PinMajorVersionsOnPackageReference" BeforeTargets="ResolvePackageAssets">
  <ItemGroup>
    <PackageReference Update="@(PackageReference)"
                      Version="[%(Version), $([System.String]::Copy('%(Version)').Substring(0, $([System.String]::Copy('%(Version)').IndexOf('.')))).999.999]"
                      Condition="'$([System.String]::Copy(`%(Version)`).Contains(`[`))' == 'false' AND
                                 '$([System.String]::Copy(`%(Version)`).Contains(`(`))' == 'false' AND
                                 '$([System.String]::Copy(`%(Version)`).Contains(`*`))' == 'false'" />
  </ItemGroup>
</Target>

A full Directory.Build.targets that is also compatible with central package management can be found on my gists.
The string handling can probably be simplified.

It works by replacing all specific versions (those that do not themselves define a range or have wildcards in them) with a version range with the specific version as inclusive minimum and some reasonably high minor version within the same major version as the inclusive maximum.

It will effectively replace Version="<version>" with Version="[<version>, <version.Major>.999.999]".

I chose an inclusive upper bound instead of the exclusive -0 upper bound to avoid issues with nuget gallery and NU5104.
The version template can of course be replaced by something else.

[lauxjpn]

To solve this issue in a backward compatible way, I suggest to support a syntax like [1.0.0, 2.0.0-) (trailing dash), that would then also exclude prereleases.

[ramonsmits]

There really is not a single developer on earth and beyond that would want to match version 2.0.0-rc.2 when they specify range [1.0.0, 2.0.0).

[ramonsmits]

I think it would be a major breaking change to the most basic part of NuGet to change this behavior.

True, but it would fix an even bigger confusion. In reality, introducing this "huge" breaking change actually would only fix things!

[zivkan]

I just created a proposal for a warning to help guide customers to use a syntax that achieves the desired outcome, without causing breaking behaviour (well, as long as you don't count customers who use TreatWarningsAsErrors as breaking): #12423. Feel free to add a 👍 reaction to the new issue to upvote it and increase its prioritization.

[baronfel]

I was digging into how other ecosystems approach this and found that Node's semver package and the Rust semver crate both do not appear to have the same satisfaction rules as NuGet does. First, the npm semver package:

❯ npm install -g semver
❯ semver -r "[1.0.0, 2.0.0)" 2.0.0-alpha.1

❯

The empty line here meaning that the provided version doesn't match the range.

Now, rust:

use semver::{BuildMetadata, Prerelease, Version, VersionReq};

fn main() {
    let req = VersionReq::parse(">=1.0.0, <2.0.0").unwrap();

    // Check whether this requirement matches version 2.0.0-alpha.1 (no)
    let version = Version {
        major: 2,
        minor: 0,
        patch: 0,
        pre: Prerelease::new("alpha.1").unwrap(),
        build: BuildMetadata::EMPTY,
    };
    assert!(req.matches(&version)); // this will fail

    // Check whether it matches 1.3.0 (yes it does)
    let version = Version::parse("1.3.0").unwrap();
    assert!(req.matches(&version));
}

❯ cargo run
   Compiling rust-semver-test v0.1.0 (D:\Code\Scratch\rust-semver-test)
    Finished dev [unoptimized + debuginfo] target(s) in 0.28s
     Running `target\debug\rust-semver-test.exe`
thread 'main' panicked at 'assertion failed: req.matches(&version)', src\main.rs:14:5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
error: process didn't exit successfully: `target\debug\rust-semver-test.exe` (exit code: 101)

So neither of these ecosystems behave the same as we do currently. I dug a bit further and both seem to point to section 5 of the supplemental ranges.md, which I'll reproduce here:

Inclusion of PRERELEASE idenfiers in Comparator Sets.
SemVer Versions that include PRERELEASE identifiers are assumed to be unstable and/or incomplete.

Additionally, the presence of PRERELEASE identifiers in a version such as I.J.K-PRERELEASE causes the SemVer Version to have a lower precedence than I.J.K. Thus, it could cause a Range such as <2.0.0 to include the version 2.0.0-rc.0, which likely contains breaking API changes that the consumer is not prepared to handle.

To avoid surprising behavior for consumers, the inclusion of SemVer Versions with PRERELEASE identifiers is as follows.

• SemVer Versions containing PRERELEASE identifiers MUST NOT be included by a SemVer Comparator Set unless they are included by all of the Comparators in the Comparator Set, and one or more of the following conditions are met:
  • The implementation has provided the user with an option to explicitly include PRERELEASE versions, and the user has set this option. This SHOULD NOT be the default behavior when resolving software dependencies.
  • One or more of the Comparators in the Comparator Set have the same MAJOR, MINOR, and PATCH version as the SemVer Version string being considered, and has a PRERELEASE version, and would normally include the SemVer Version string by virtue of precedence comparison.
    For example, the Range >=1.0.0-alpha would include the Version 1.0.0-beta but not the Version 1.0.1-beta.
• SemVer Version strings without a PRERELEASE version are included in a SemVer Comparator Set if they are included by all of the Comparators in the Comparator Set.

To my reading, this suggests that since the range [1.0.0, 2.0.0) doesn't contain any PRERELEASE identifiers in either of the Comparators in the Comparator Set, they MUST NOT be included in the comparator set.

Am I reading this wrong? Happy to be told so!

[zivkan]

Good find @baronfel !

For what it's worth, that ranges spec was created in 2020, so much more recent than NuGet's implementation (I can find NuGet's VersionRange.cs was copied from another repo in 2014, but I can't find the repo where it was copied from, to figure out how long that file has existed), and it's not linked to on https://semver.org, which makes it harder to discover. But if we change behaviour and it breaks people, at least we have something to point to as justification.

For what it's worth, there have been a small number of times in my time in NuGet where changes that seemed safe enough, and a good idea benefiting most customers, but broke a team working on a major product, and I think once it even got escalated though to high level management. So I fully understand my team mates hesitation in introducing breaking changes. If we make the change and it breaks the entire Office build system for example, or some major customer, I wouldn't want to be the engineer who added the breaking change in the first place.

[nkolev92]

There really is not a single developer on earth and beyond that would want to match version 2.0.0-rc.2 when they specify range [1.0.0, 2.0.0).

@ramonsmits

That's not the complete behavior.
If no one else in the graph asks for a prerelease version, then the prerelease version won't be included.
Take this example:

Packages on server:

• A 1.0.0
• B 2.0.0-alpha.3

A 1.0.0 declares a [1.0.0, 2.0.0) dependency on B.

If the project declares:

A 1.0.0 as a dependency, restore will fail with NU1103.

#6434 (comment) has a more detailed explanation, but prerelease versions will be allowed only when some other part of the graph specifically wants those prerelease versions.

[ramonsmits]

@nkolev92 see #12082 (comment)

[nkolev92]

I'm not sure I follow that example.
For direct dependencies, NuGet will resolve the lowest specified and report a conflict.

[Fact]
        public async Task Test()
        {
            // Arrange
            using var pathContext = new SimpleTestPathContext();
            var logger = new TestLogger();
            var projectName = "TestProject";
            var projectPath = Path.Combine(pathContext.SolutionRoot, projectName);


            var sources = new List<PackageSource> { new PackageSource(pathContext.PackageSource) };

            // packages in the project.
            var project1Json = @"
                {
                  ""version"": ""1.0.0"",
                  ""frameworks"": {
                    ""net472"": {
                        ""dependencies"": {
                            ""A"": ""[5.0.0,6.0.0)"",
                            ""B"": ""[1.0.0,2.0.0)""
                        }
                    }
                  }
                }";

            var A500 = new SimpleTestPackageContext("A", "5.0.0");
            A500.Dependencies.Add(new SimpleTestPackageContext("B", "[2.0.0,3.0.0)"));

            // Packages on the server.
            await SimpleTestPackageUtility.CreateFolderFeedV3Async(
                pathContext.PackageSource,
                PackageSaveMode.Defaultv3,
                    A500,
                new SimpleTestPackageContext("A", "5.0.0-rc.1"),
                new SimpleTestPackageContext("A", "5.1.0-rc.1"),
                new SimpleTestPackageContext("A", "5.1.0"),
                new SimpleTestPackageContext("A", "6.0.0-rc.1"),
                new SimpleTestPackageContext("A", "6.0.0"),
                new SimpleTestPackageContext("B", "1.0.0"),
                new SimpleTestPackageContext("B", "2.0.0-rc.1"),
                new SimpleTestPackageContext("B", "2.0.0"),
                new SimpleTestPackageContext("B", "2.0.1"),
                new SimpleTestPackageContext("B", "3.0.0")
            );

            // set up the project
            var spec = JsonPackageSpecReader.GetPackageSpec(project1Json, projectName, Path.Combine(projectPath, $"{projectName}.json")).WithTestRestoreMetadata(); var request = new TestRestoreRequest(spec, sources, pathContext.UserPackagesFolder, logger)
            {
                LockFilePath = Path.Combine(projectPath, "project.assets.json"),
                ProjectStyle = ProjectStyle.PackageReference
            };
            var command = new RestoreCommand(request);

            // Act
            var result = await command.ExecuteAsync();

            // Assert
            result.Success.Should().BeTrue(because: logger.ShowMessages());
            result.LogMessages.Should().HaveCount(1);
            result.LogMessages.Single().Code.Should().Be(NuGetLogCode.NU1605); // Downgrade because the project specified a direct dependency to B.

            var targets = result.LockFile.Targets.Single();
            targets.Libraries.Should().HaveCount(2);
            targets.Libraries.First().Name.Should().Be("A");
            targets.Libraries.First().Version.Should().Be(NuGetVersion.Parse("5.0.0"));
            targets.Libraries.Last().Name.Should().Be("B");
            targets.Libraries.Last().Version.Should().Be(NuGetVersion.Parse("1.0.0"));
        }

As long as no one in the graph specifies a prerelease dependency, no prerelease dependencies will selected. That's why https://learn.microsoft.com/en-us/nuget/reference/errors-and-warnings/nu1103 happens.

[ramonsmits]

I'm sorry, I made a typo and corrected that comment. There will be no conflict because of the range behavior that allows the prerelease of the next major to be selected that (due to semver) likely has a breaking API change thus cannot compile or even worse compile but have breaking runtime behavior.

I've run into this behavior several times now over the year and it really is unwanted. Its not something developers can fix as they are dependent on the package maintainer. 100% of package maintainer really don't want to state they are compatible with a pre-release version of the next major even when that version hasn't been released.

What package maintainers want to express is... HEY, I'm compatible with version 4.1+ when they specify [4.1.0,5.0.0).

Take this comment:

• [Bug]: VersionRange [1.0.0, 2.0.0) matches version 2.0.0-alpha.1 which can break package graphs #12082 (comment)

Which links to:

• [Feature]: Allow to specify version range for packagereferences while using the latest / a specific version during build. #11842

You really think that a developer that states the following wants to express they are compatible with 13.0 pre-release packages?

<PackageReference Include="Newtonsoft.Json" Version="[12.0,13.0)" />

According to your team that is a maintainer error and they should have expressed it as [12.0,13.0-0). That would be a workaround and completely not obvious. That is why on Nuget this is so common.

I'll rephrase my earlier comment where I stated that introducing this "breaking change" would actually only benefit all developers as it actually would only fix things!

[ramonsmits]

So when will this "massive breaking change" that will only fix things finally be resolved?