search

jimporter / mike

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

Allow new versions to replace existing aliases when `--update-aliases` is set #169

Closed Wolf2323 closed 11 months ago

Wolf2323 commented 1 year ago

Hello, I'm a developer at BetonQuest. Currently, we use 2.0-DEV for development versions and 2.0 as an alias.

This pull request enhances the --update-aliases flag by allowing it to overwrite existing aliases with a new version. Previously one had to first remove the alias to then create a new version with the same name.

Example based on our case:

  1. Assume you have a version 2.0-DEV and an alias 2.0 pointing to that version.
  2. You run mike deploy 2.0 --update-aliases.
  3. With this change you will end up with two versions: 2.0-DEV and 2.0, 2.0 is now not an alias of 2.0-DEV anymore. Without this change mike would throw an exception.
jimporter commented 1 year ago

This pull request enhances the --update-aliases flag by allowing it to overwrite existing aliases with a new version. Previously one had to first remove the alias to then create a new version with the same name.

Thanks for the patch. I think it makes sense to allow upgrading an alias to a regular version. However...

  1. Assume you have a version 2.0-DEV and an alias 2.0 pointing to that version.

  2. You run mike deploy 2.0 --update-aliases.

  3. With this change you will end up with two versions: 2.0-DEV and 2.0, 2.0 is now not an alias of 2.0-DEV anymore. Without this change mike would throw an exception.

... I think this is a problem lying in wait for you. With this change, you now have an orphaned 2.0-DEV version. Either a) that just points to now-outdated in-development docs for 2.0, or b) you plan to use this for the next release after 2.0. In the former case, I think you'd want that to point to the final 2.0 docs. In the latter, you probably want a new identifier for your in-development docs (e.g. 2.1-DEV or 3.0-DEV); m.n-DEV comes before m.n as a general rule, so you'd instead want a version identifier that marks it as a prerelease for whatever comes after 2.0.

In this case, what I'd recommend is for your version identifier to be 2.0, even during development, but to set the title to 2.0 (devel) or whatever. That's what I do with bfg9000 (which is the project that led to mike's creation, so most of mike's features are built around the flow I use there).

Wolf2323 commented 1 year ago

I forgotten, that there is also the title for a version. So i like your approach and will set a title, while using the final name for the version.

Its up to you if you just want to close this PR, or may merge it, but then maybe we should change the example in the README, to not mislead other people.

Wolf2323 commented 1 year ago

We adjusted your workflow to your approach, and i was about to merge it, when i realized two things:

  1. Migrating an old version format to a new one is exactly the use case for this PR, when you already have an version with that alias and you now need to migrate it to a new version format.

  2. Your approach is not working for us in the expected way. We already have a software version 1.12.10 and the corresponding docs version is 1.12 (Because bug fix versions should not change docs in a significant way) and now we already working on the new software version 1.12.11. Currently the corresponding docs version is 1.12-DEV. But when we now change it so it is 1.12 and only has an alias 1.12-DEV it conflicts with the already released one.

Just in case you want to have a look on your version file: https://github.com/BetonQuest/BetonQuest/blob/gh-pages/versions.json

jimporter commented 1 year ago
  • Migrating an old version format to a new one is exactly the use case for this PR, when you already have an version with that alias and you now need to migrate it to a new version format.

That's what most of the subcommands other than mike deploy are for: if you need to shuffle things around, you can use mike delete or similar. In fact, you should feel free to do this locally for one-off cases: since mike just operates on your gh-pages branch, so as long as your checkout is up-to-date, you can perform all maintenance locally and then push upstream. This also gives you a chance to check your work before pushing.

  • Your approach is not working for us in the expected way. We already have a software version 1.12.10 and the corresponding docs version is 1.12 (Because bug fix versions should not change docs in a significant way) and now we already working on the new software version 1.12.11. Currently the corresponding docs version is 1.12-DEV. But when we now change it so it is 1.12 and only has an alias 1.12-DEV it conflicts with the already released one.

I don't think you need an alias here at all: it sounds like what you want are two independent doc versions: 1.12 and 1.12-next. Once 1.12.11 is completely ready to go, you could deploy your docs to 1.12. After that, you'll likely have a source branch ready to starts work on 1.12.12, which becomes your new 1.12-next version.

You could eventually make 1.12-next be an alias to 1.12, but I'd only do that once you're sure there will be no further releases in the 1.12 series. In that case, you could call mike delete 1.12-next && mike alias 1.12 1.12-next.

EDIT: You could also just leave 1.12-next around in case you need to make a high-priority update to that branch (e.g. to fix a security bug). To help with that, maybe mike should have the ability to hide certain versions from the dropdown. Then you can keep them around but they don't pollute your version list.

jimporter commented 11 months ago

I've merged this as 0481f92 (after shuffling a couple of things around). Thanks for the patch! Version 2.0.0 should be out sometime this week; I'm just doing some final testing now before I tag it.