[bug] Documentation issues with example for version ranges

[snickl]

Describe the bug

Hey,
at the bottom of https://docs.conan.io/2/tutorial/versioning/version_ranges.html it seems to say that 1.0-pre.1 will be included in the range [>1 <2, include_prerelease], but I tried it and it isn't.
Maybe it's meant to say >=1?

I also got quite confused by the upper bound where it says 2.0-pre1 is outside <2, which it is.
But a bit further up it says

A pre-release happens earlier in time than the release it is qualifying. So 1.1-alpha.1 is older than 1.1, not newer.

So logically, 2.0-pre1 should be included, because it's older=less than 2.

The real rule appears to be that pre-release qualifiers on packages are ignored in ranges comparisons.
As in "1.0-pre.1 is included with >=1 because for purposes of comparison it's 1.0, and not something less than 1.0".

Maybe the documentation can be made a bit clearer in that regard to avoid confusion for others.
Thanks!

How to reproduce it

No response

[memsharded]

Hi @snickl

Thanks for your feedback.

at the bottom of https://docs.conan.io/2/tutorial/versioning/version_ranges.html it seems to say that 1.0-pre.1 will be included in the range [>1 <2, include_prerelease], but I tried it and it isn't.
Maybe it's meant to say >=1?

Yes, that seems a bug in the docs, 1.0-pre.1 is part of the 1.0 releases, and would be excluded if strictly greater than 1, but included in >=1

I also got quite confused by the upper bound where it says 2.0-pre1 is outside <2, which it is.

Yes, this should be the case

A pre-release happens earlier in time than the release it is qualifying. So 1.1-alpha.1 is older than 1.1, not newer.

This is correct, a 1.1-alpha.1 happens early in time than the 1.1

So logically, 2.0-pre1 should be included, because it's older=less than 2.

Not really, even if 2.0-pre.1 happens earlier than 2.0, it is still excluded when a strict <2 limit is applied, because the 2.0-pre.1 is still part of the 2.0 release train.

In other words, when a range defines [... <2] and the new major version 2.0 is coming with breaking changes over the API, it will create a 2.0-alpha pre-release, that is explicitly excluded from the range. That range with pre-releases enable can accept prereleases for minor versions such as 1.9-pre.1 that are expected to be API compatible.

Lets move this to the docs repo to fix the first part, and lets see if the other points can be clarified.
Thanks very much for raising this issue!

[snickl]

Ah, that makes a lot of practical sense, even if it's confusing when you think about it purely in terms of a number line.
Leaving the issue open since I reckon you'll be using it to track the work.
Thanks!

[memsharded]

Ah, that makes a lot of practical sense, even if it's confusing when you think about it purely in terms of a number line.

yes, exactly, the pre-releases can be very tricky with regard the comparison conditions, but we learned from users that in practical terms, that is the expected behavior, because that is how pre-releases are being used in practice.

Yes, this ticket should stay open, it will be closed by a future PR that will fix that in the docs for next 2.20. Thanks!

[snickl]

Hey @memsharded, I think I just came across another thing that fits here quite well:
It seems that core.version_ranges:resolve_prereleases actually has three settings:

• unset: Don't resolve prereleases, but respect include_prepreleases in a range
• True: Resolve prereleases
• False: Never resolve prereleases, even if include_prereleases is given in a range

I haven't made explicit tests, but this explains best the behavior I've seen today.
In case it's relevant, the prerelease version is declared in a platform_requires.

And in the "Note" box at the bottom of Version ranges it says include_prereleases once and include_prerelease twice. I checked the code and it actually doesn't seem to matter (if "include_prerelease" in t:), but maybe the docs could clarify that both are supported and maybe which is preferred.

[memsharded]

Thanks for the hints @snickl

Indeed your observations are correct, core.version_ranges:resolve_prereleases is tri-state with those possible values and behaviors.

Lets try to incorporate that feedback into the docs, thanks again!