[Bug] Read the Docs version switcher is b0rken

[niccokunzmann]

Describe the bug

The version switcher does not work:

• branch 6.x is a 404
• switching from 6.x to 7.x opens a 404 page

To reproduce

https://icalendar.readthedocs.io/en/stable/index.html

Expected behavior

We should be able to view all versions
6.x must have a deprecation notice at the top

• fix the version switcher
• document steps in maintenance.rst what to do when releasing a new major version

Additional context

• version 7.0.0 #1191
• Update version to '6.x' in version-switcher.json #1039

[stevepiercy]

Well, poop. I configured RTD and the version-switcher.json file as it should be, but it still doesn't switch correctly for 6.x and 7.x (stable). I'll try again tomorrow.

[stevepiercy]

I got 6.x to work as not stable. Sneaky setting in conf.py. Updated docs.

Still, wtf is up with stable?

[niccokunzmann]

Would you like me to have a look at some point? 7.x was unstable for so long... Maybe it just got used to it. Hm. ;)

[stevepiercy]

@niccokunzmann I figured it out, pushed commits directly to main, including docs.

You might need to force reload the switcher to purge it from browser cache.

https://icalendar.readthedocs.io/en/latest/_static/version-switcher.json

You'll need to cut a new 7.0.1 tag and release, carefully following the changes in https://icalendar.readthedocs.io/en/latest/contribute/maintenance.html#new-releases. I think you'll only need to toggle the setting for the "stable" release as described in Step 3.

This is really annoying, and provides a very good reason to cut a 7.x branch now, develop on main, and backport changes to 7.x for an actual release. That will change the release manager's workflow slightly, but I think it's a better workflow without all the conditional "if"s and "else"s.

[niccokunzmann]

Ah. Ok.

When I read the documentation, it does not distinct between a MAJOR release and a STABLE release.
https://icalendar.readthedocs.io/en/latest/contribute/maintenance.html#new-releases

Is it correct that we want to have
"show_version_warning_banner": True,
in all branches except 7.x for now?

[stevepiercy]

Correct. That would avoid toggling the setting on main back and forth, before and after cutting a release. That also assumes you would cut a release from the 7.x branch, and not main. main is only where development happens, and stuff gets backported to 7.x when you're ready to make a release.

[niccokunzmann]

Cool. That seems to be all I needed to know for now.