Notifications: logic behind non-latest version

[humitos]

It seems there is some hidden logic in the old implementation of this feature. This comment called my attention regarding branches vs. tags: fabric/fabric#2255 (comment). There is a link to readthedocs/readthedocs.org#3268 which explains a little bit of the history here.

We should clearly define what's the logic behind our semver comparisons.

[humitos]

At this point, I think we should implement "the most basic and strict version of semver" first and then allow people to write their javascript function to replace this basic logic. We will never cover all the cases and, in fact, I found that a lot of cases are edge cases:

• calver
• tags have priority over branches
• versions with prefixes like release/2.0 or v3.1, etc

I think this will give users something that works in a reliable way for specific use case, but also the flexibility to customize it as they want if they have a particular use case.

[humitos]

The logic I have in mind would be similar to:

The simple case, is the ✅ valid version: (semver.valid). They look like 1.2.1 and v3.1.6 and =4.1.1. However, the ❗ invalid version is more complex and we need to loose it a little here:

• it has to have / on its name:
  • release/2.1
  • rel/2.1
  • development/release/4.1.1
• it has to have at least a "minor" part on the name (release-1 is not valid)
• the "major" part of the version has to be isolated (between / or - or .)
  • release-candidate-2.1 ➡️ 2.1.0
  • project-name-1.6/release ➡️ 1.6.0
  • test-404-page ➡️ invalid (otherwise it gives us 404.0.0 when calling semver.coerce)

While writing this down, I found it's not super accurate nor easy to explain, but I think this implementation could cover most of the use cases. We can tweak it a little as we go.

However, people with strict/different needs (like calver), they should write their own logic for this.

As examples, our test-builds project detects the highest version as custom-404-page because when coerced it's 404.0.0. By disabling that version, it detects py3.10 as the highest version when coerced as 3.10. I'm not sure how to solve these cases 🤔

[humitos]

@stsewd @agjohnson @ericholscher do you have a better and simpler idea for this?

[agjohnson]

Hrm, honestly I'm not sure. Comparing versions that are already semver makes sense, but coercion looks like the wrong tool to rely on here. For every case we get right using coercion, I'm sure there will be plenty others that we get wrong.

I'd say if it isn't obviously a semver version, we can't support it with this warning. At least not right now. I still think there is more was could do to give the user the ability to tell us what is latest, instead of us using some amount of magic to guess. We've talked about surfacing this sort of behavior in automation rules, perhaps related to latest/stable rules, which I still think is a really good idea.

Actually, thinking more, I sort of just want a Version.is_outdated that the user controls manually or through automation rules.

[humitos]

What about a pretty simple logic to start with?

• if there are the latest and stable versions active, we show "you are reading the development version, the stable version is at ..." when reading latest
• if there are stable and more active versions, when navigating other versions we show "you are not reading the stable version, read it..." if the version people is reading is not the stable one

I think this simple approach can work to start with. In the end, the most accurate approach would be a customized one by the user, but we are not there yet.

Also, the implementation for this approach looks pretty simple, and seems easy to explain to users.

I think we can start by using simple logic we know and control like stable and latest versions.

[humitos]

I still think there is more was could do to give the user the ability to tell us what is latest

I like this idea if we can allow them to tell this us in an automated way. Otherwise, I think it will become "another tool to update each time a new release is done" and make the process a little more tedious. Making this automated somehow is one of the Read the Docs features that I don't want to loose.

[humitos]

issues stemming from the application being not super transparent with how we determine latest/stable

(from readthedocs/readthedocs.org#5319 (comment))

This makes me think again about the logic behind this addon. Maybe making our logic latest/stable dependent is not a good idea if users have problem understanding how we determine those. This is a good point to avoid this pattern maybe.

[agjohnson]

These are all good points.

Does offering a configuration option help at all here?

I don't quite have a strong opinion here yet, but so far I feel:

• An explicit option is best, but agreed we're not there yet
• Semver (without coercion) probably works for most/many cases
• We could fall back to using latest/stable when semver doesn't work
• If the user can configuration this or at least disable the notifications easily, this seems like maybe enough until we do get an explicit option on Version objects