search

jimporter / mike

Manage multiple versions of your MkDocs-powered documentation via Git
BSD 3-Clause "New" or "Revised" License
551 stars 47 forks source link

Change the order of versions in `versions.json` #82

Closed ofek closed 2 years ago

ofek commented 2 years ago

From: https://github.com/squidfunk/mkdocs-material/issues/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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

Has there been any update on this?

jimporter commented 2 years ago

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

ofek commented 2 years ago

Has this been implemented?

jimporter commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

When might this be released?

jimporter commented 2 years ago

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 commented 1 year ago

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

jimporter commented 1 year ago

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 commented 1 year ago

Does that work on Windows?

jimporter commented 1 year ago

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

ofek commented 1 year ago

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):

image