Change the order of versions in versions.json

[ofek]

From: squidfunk/mkdocs-material#3251

Currently, textual versions like dev or master come after real numeric versions and are not easy to find/select when there are many versions.

[jimporter]

The version for your documentation should be an actual version number (in this case, you should set it to be whatever the version will be when you release it). If you want to show dev or master, then you can 1) set that as an alias for the URL and/or 2) specify a custom title for the version, which will be displayed in the dropdown.

[ofek]

Hmm, it most cases wouldn't the last release also be dev? Most people don't automatically bump to a beta/rc version after a release

[jimporter]

I'd say it's generally good practice to update your project's version to something that sorts "after" the last-released version immediately after you've published the release. That way it's much clearer what version people are on, even if they're using a dev build. I know I'd find it confusing if someone said they were on 1.2.3, but they were actually on a development version that will become 1.2.4 or 1.3 or 2.0...

[jimporter]

Reopening this for now; I think there's at least some argument that "version" strings that don't start with a number should always be treated as newer than a regular numbered version. I'm not sure this makes sense for all cases (and I'd still strongly recommend the strategy I describe above), but something like this might account for cases like this without harming the recommended strategy of always using a numbered version.

[ofek]

Has there been any update on this?

[jimporter]

Not at the moment, no. I've been super busy with other things and haven't had time to devote to this yet.

[ofek]

Has this been implemented?

[jimporter]

No, it hasn't. Given the discussion in #52, it will probably be some time before we settle on a solution that's flexible enough and which works with mkdocs-material's "latest version" banner.

[jimporter]

In the meantime, it would probably be fairly straightforward to post-process the versions.json file after calling mike deploy ... to reorder the list of versions in whatever way makes sense for your project. That has the benefit that you have 100% control of the order, and you don't have to wait for a general-purpose implementation of the feature.

[jimporter]

This should be fixed now; the logic is that versions without a leading digit are "development" versions, so effectively they're in a higher epoch. Otherwise though, they're sorted like versions; in particular, this means that post is newer than pre, even though pre comes later alphabetically.

[jimporter]

@squidfunk Just a heads up, since this change might affect mkdocs-material.

mike now sorts the versions in versions.json so that development versions (those without a leading digit) are newer than other versions. This might cause issues with the "you're not on the latest version" banner in the Material theme, so I figured I should let you know before it bites you.

[squidfunk]

Well, maybe the semantics need to be redefined a little. Currently we look for the latest alias to show the banner, i.e. when the alias is not latest, the banner is shown. We might need to redefine the semantics here. If this is needed, please open a new issue, explaining what should change, i.e. when the version banner needs to be shown.

[jimporter]

Ah, that should be fine then. Your current way shouldn't run into any trouble with this change. (Maybe there's room for different ways to detect the latest version, but that seems fine to me, so long as users are happy setting a latest alias.)

[ofek]

When might this be released?

[jimporter]

Probably not for a while, since this project is a low priority for me. If you're waiting on this feature for something, I'd recommend using the development builds (with the usual caveat that there may be other bugs).

[ofek]

Is there any chance there will be a release soon? Can I assist in any way please?

[jimporter]

The absolute bare minimum for releasing v2.0 is to resolve #106. I haven't had time to work on this, but if someone can perform testing, that would help move things along.

[ofek]

Does that work on Windows?

[jimporter]

Well, the automated tests using symlinks pass on Windows systems, so I'd say yes.

[ofek]

By default, only administrators are able to use those https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links#default-values

See also this comment from a CPython core developer at Microsoft regarding a proposal to use symlinks in a packaging standard https://discuss.python.org/t/discuss-pep-662-editable-installs-via-virtual-wheels/9071/97

Those tests fail on my machine, and I have the highest privileges (I'm guessing I never enabled the option):