Chooser links on Release Notes pages yield a 404

[DanielSwain]

Expectation

When viewing a particular version of the Release Notes, if a different version is chosen using the chooser in the lower right, then that version of the Release Notes should be displayed.

Actual Behavior

Go to any version of the Release Notes, click the chooser, and then choose any version other than the one being viewed. A 404 is the result.

Additional Reference

Slack conversation concerning this issue.

[gasman]

As per the Slack conversation, I wouldn't consider this a bug. It's standard practice among open-source projects for each version's documentation to include the full set of release notes for all versions that came before it - rather than just a single release notes page for that specific version. So, for example, you can view the 4.0 release notes as part of the 4.1 documentation, but if you then switch to version 3.0, you'd be trying to view the 4.0 release notes within the 3.0 documentation, which clearly don't exist because version 4.0 didn't exist when those were published - so the 404 error is expected.

I see that Django handles this by limiting the version chooser to just the versions where the page in question exists - so, for example, https://docs.djangoproject.com/en/4.1/releases/4.1/ only offers 4.2, 5.0 and dev in the version chooser as these are the only other instances of the docs that contain 4.1 release notes. I wouldn't be averse to adopting this approach, if readthedocs supports it.

[thibaudcolas]

Copying more of the Slack conversation:

@thibaudcolas
do you think this is something we could make better with redirects? :thinking_face: it’s a manual process but we can set up arbitrary redirects in the ReadTheDocs admin.
@DanielSwain
I'm not sure how ReadTheDocs works behind the scenes
@Thibaud (he/him)
, so I couldn't comment on redirects. It just seems odd to me that the same chooser that is rendered on all the other documentation pages can't also be used for the Release Notes pages. The error I described only happens on the Release Notes pages because the urls are malformed in the chooser dropdown menu.
@thibaudcolas
What I had understood from what you said earlier was that you’d expect the version chooser to work differently on those pages? It’s the same version chooser as everywhere else

@thibaudcolas
the problem is that the version switcher takes you to the page you’re on in the version you select – while you’re asking if we could have it instead go to a different version’s release notes rather than a 404 when switching versions on a release notes page?

@DanielSwain
Yes, I would like the version chooser to take me to the previous version of the Release Notes when I choose a previous version while on a Release Notes page. urls for Release Note pages currently look like this: https://docs.wagtail.org/en/stable/releases/5.1.html

Might this problem be remedied with a change to the url structure by making the version a part of the url rather than a part of the filename and then always naming the html file something like "release_notes.html"? Perhaps that way the chooser would always go to "release_notes.html". (edited)

@thibaudcolas
What you’re suggesting means we’d need to completely reset that release_notes.html file in every release, so – I’m not sure

@thibaudcolas

@thibaudcolas
There might be a way though for us to change what we publish so it’s clearer

[thibaudcolas]

Looking at redirects options supported by Read the Docs, this seems trickier than I thought. Switching versions by following a link also feels like a bit too much magic.

So – I’d instead recommend we build a custom 404 page. We can start with static content to help people understand where they landed. We could also build something more clever where the 404 page’s content could vary depending on what URL / version it’s served on.

[gasman]

@thibaudcolas How about we add a redirect rule from /releases/* to /releases/index.html (with the 'force redirect' option unchecked)? This would then kick in for any 404s under /releases/, and in the case of a user getting a 404 because they switched from a newer to an older version, the page they're looking for will be right at the top of the index.

[thibaudcolas]

@gasman ah great! I was envisioning we’d want to redirect to the correct specific version, but yeah redirecting to the index seems like a good improvement already.

[thibaudcolas]

Just set up in RTD, this is all looking good to me:

• From URL: /releases/*
• To URL: /releases/index.html
• HTTP status code: 302 - Temporary
• Force redirect: unchecked

Here’s what the experience looks like:

• Start from looking at the v5.0.x release notes from stable – all good
• Switch versions to look at those release notes in the v5.0.x version of the docs – all good as well
• Switch versions to look at those release notes in the v4.2.x version of the docs (does not exist) – now redirects to the releases index.

[thibaudcolas]

@DanielSwain this won’t implement exactly what you’re after, I believe for that to work we’d need a custom 404 page I believe.

I still think this could be a worthwhile investment but perhaps would warrant its own issue?