Unstable versions, newer than newest stable, display "old version" message

[MateuszKubuszok]

Example:

• https://chimney.readthedocs.io/en/1.0.0-rc1/
• 1.0.0-RC1 is the newest release (but not yet a stable one, it's a release candidate)
• versions shows it as the newest version (which isn't the same as "latest", as "latest" is master)
• addons configuration:
  • addons enabled
  • flyout sorting = Python Packaging (Alphabetical sorting, SemVer and custom pattern=MAJOR.MINOR.PATCH[-PYTAGNUM] didn't work as intended, milestones/release candidates were displayed before stable release, etc, so it's the least wrong sorting where only milestones are at the end, out of order, and RC and stable are correctly sorted)
  • show a notification on a non-stable and lastest = true

I'd assume that documentation for non-stable version - newer than newest stable - would rather have the same banner as latest ("This is the latest development version" or similar) rather than "This may be an older version of this documentation" which might be confusing to the users. Ideally, they would have dedicated message like, "This is preview release, expect things might change, or use the stable for now", but if the choice is between the 2 existing ones, I think less confusing would be message from the unstable version.

[humitos]

HI @MateuszKubuszok. Thanks for opening this issue.

Unfortunately, I'm not 100% sure to understand what's not working as expected. Going to https://chimney.readthedocs.io/en/1.0.0-rc1/ I see the following versions in the flyout:

latest
stable
1.0.0-rc1
0.8.5
0.8.4
0.8.3
0.8.2
0.8.1
0.8.0
0.8.0-rc1
0.7.5
0.7.4
0.7.3
0.7.2
0.7.1
0.7.0
0.6.2
0.6.1
0.6.0
0.5.3
0.5.2
0.5.1
0.5.0
0.8.0-m1
1.0.0-m1
1.0.0-m2
1.0.0-m3
1.0.0-m4
1.0.0-m5
1.0.0-m6
1.0.0-m7

Is this sorting correct for you? If not, how it should be sorted?

I'd assume that documentation for non-stable version - newer than newest stable - would rather have the same banner as latest ("This is the latest development version" or similar) rather than "This may be an older version of this documentation" which might be confusing to the users. Ideally, they would have dedicated message like, "This is preview release, expect things might change, or use the stable for now", but if the choice is between the 2 existing ones, I think less confusing would be message from the unstable version.

So, should it show a message informing that This version is unreleased yet, expect things might change, or use the stable for now?

[MateuszKubuszok]

Hi @humitos!, Thanks for the reply.

The best sorting would be:

latest
stable
1.0.0-rc1
1.0.0-m7
1.0.0-m6
1.0.0-m5
1.0.0-m4
1.0.0-m3
1.0.0-m2
1.0.0-m1
0.8.5
0.8.4
0.8.3
0.8.2
0.8.1
0.8.0
0.8.0-rc1
0.8.0-m1
0.7.5
0.7.4
0.7.3
0.7.2
0.7.1
0.7.0
0.6.2
0.6.1
0.6.0
0.5.3
0.5.2
0.5.1
0.5.0

as I believe it would be according to semver and how it's interpreted by e.g. Maven. I wasn't able to reproduce that order by testing each option on addons page (I tried all with a refresh in-between, and I also tried custom pattern MAJOR.MINOR.PATCH[-PYTAGNUM], each time something was off).

For comparison, what you listed was output when I selected Python Packaging. When I select
SemVer, I get:

0.8.0-m1
1.0.0-m1
1.0.0-m2
1.0.0-m3
1.0.0-m4
1.0.0-m5
1.0.0-m6
1.0.0-m7
0.5.0
0.5.1
0.5.2
0.5.3
0.6.0
0.6.1
0.6.2
0.7.0
0.7.1
0.7.2
0.7.3
0.7.4
0.7.5
0.8.0-rc1
0.8.0
0.8.1
0.8.2
0.8.3
0.8.4
0.8.5
1.0.0-rc1
stable
latest

even though still selected "Flyout sorting latest stable at the beginning" it's now ascending order, and 1.0.0-milestones are lower than 0.5.0. Sorting alphabetically shows:

0.5.0
0.5.1
0.5.2
0.5.3
0.6.0
0.6.1
0.6.2
0.7.0
0.7.1
0.7.2
0.7.3
0.7.4
0.7.5
0.8.0
0.8.0-m1
0.8.0-rc1
0.8.1
0.8.2
0.8.3
0.8.4
0.8.5
1.0.0-m1
1.0.0-m2
1.0.0-m3
1.0.0-m4
1.0.0-m5
1.0.0-m6
1.0.0-m7
1.0.0-rc1
latest
stable

It's almost correct but again, its ascending order and milestones and release versions are higher here than normal versions. Finally, my own attempt with MAJOR.MINOR.PATCH[-PYTAGNUM] shows:

latest
stable
1.0.0-rc1
0.8.5
0.8.4
0.8.3
0.8.2
0.8.1
0.8.0-rc1
0.8.0
0.7.5
0.7.4
0.7.3
0.7.2
0.7.1
0.7.0
0.6.2
0.6.1
0.6.0
0.5.3
0.5.2
0.5.1
0.5.0
0.8.0-m1
1.0.0-m1
1.0.0-m2
1.0.0-m3
1.0.0-m4
1.0.0-m5
1.0.0-m6
1.0.0-m7

the same as Python Packaging.

But I am be Ok with the current sorting, I believe it was sorted more or less this way before addonds become available (release versions and release candidates sorted correctly, then milestones made "before" them all).

My biggest concern is that the current message might makes it look as if something is misconfigured, because the user can see message about looking at the older version, when they are accessing the newest albeit unstable version.

Anything informing that it is pre-release rather than older versions should be ok.

[humitos]

But I am be Ok with the current sorting, I believe it was sorted more or less this way before addonds become available (release versions and release candidates sorted correctly, then milestones made "before" them all).

OK. I never seen the -m1 postfixes. Are they valid SemVer? Taking a look at the documentation from BumpVer (the underlying library we use to sort them), I see that PYTAG does not mention m, only a, b, rc, post.

I'm not sure if there is anything we can do to make the -m postfix to work, but I'm happy to receive some ideas to tweak the underlying library if that's possible (I wouldn't re-write the sort system with custom code).

My biggest concern is that the current message might makes it look as if something is misconfigured, because the user can see message about looking at the older version, when they are accessing the newest albeit unstable version.
Anything informing that it is pre-release rather than older versions should be ok.

I think this an interesting point. It could be helpful to for the front-end to realize this is an unreleased version and show a notification communicating this to the users. I'm not sure how to implement this in a way that fit our current pattern, tho. I may need to think more about this use case.

[MateuszKubuszok]

OK. I never seen the -m1 postfixes. Are they valid SemVer?

From what I understand, PEPs for Python Packaging has no such concept. But Semantic Versioning in general does allow them. In the specification I can find item 9:

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.

From what I understand SemVer is quite permissive and allows 1.0.0-whatever, not only -M. It also recognizes that "normal" version does not have them, and so everything with x.y.z-something should be consider as "smaller" than x.y.z (but "bigger" than x.y.(z-1)).

It's even clarified in 11.3:

When major, minor, and patch are equal, a pre-release version has lower precedence than a normal version:

Example: 1.0.0-alpha < 1.0.0.

I saw these and other suffixes (-SNAPSHOT, -final, -GA) quite often in libraries released on JVM in general - Java, Kotlin, Scala. -M more often in Scala where authors wanted to be absolutely sure that they could commit to the API, so they wanted users to test it and give back feedback, without promising that they should use that version on prod (example). I guess RtD might have Python libraries as the biggest userbase, but if more JVM libraries will be hosted there, I believe more of them would have such versions.

SemVer.org has a link to this regexp which shows some examples of valid versions, which one might find surprising, but they are valid.

I don't necessarily mean that some tool should hardcode Java suffixes next to Python suffixes. I just mean that SemVer is quote permissive, and each language/framework might establish some convention that would still be well within semantic versioning.

Taking a look at the documentation from BumpVer (the underlying library we use to sort them), I see that PYTAG does not mention m, only a, b, rc, post.

I suspected so. RtD was build primarily around Python-based tools (Sphinx, MkDocs), and I imagine it attracts mainly Python libraries sticking to the Python Packagins formats, so cases like mine (JVM, Scala to be specific) might have flied under the radar. From my perspective, BumpVer takes versions which (kinda) match BOTH SemVer and Python conventions and is a bit confused if someone tries to use version which matched SemVer specification but not in a way similar to Python Packaging. I cannot say how valuable such improvement would be for the community if no one else reported an issue with it.

I'm not sure if there is anything we can do to make the -m postfix to work, but I'm happy to receive some ideas to tweak the underlying library if that's possible (I wouldn't re-write the sort system with custom code).

I understand that. As I said, I am ok if the sorting stays as it now. I was mostly concerned about the wording of the notification.

[joestringer]

I'm seeing this same issue with a release candidate for an upcoming Cilium release https://docs.cilium.io/en/v1.16.0-rc.0/overview/intro/ .

Currently the versions of docs we have are:

• latest (dev, from main, has appropriate dev banner "This is the latest development version...")
• main (Generated from the latest stable major.minor.patch version, no banner 👍 )
• v1.16.0-rc.0 (Candidate for an upcoming release, currently displays "old version" banner which would ideally be worded with more of a development warning)
• v1.15 (Generated from stable maintained major.minor branch. Currently displays "old version" banner, though ideally this would not have a banner since it's the same release series as "stable")
• v1.14, v1.13 (older stable branch releases, correctly displays "old version" banner).