Documentation on readthedocs - links to older releases return 404 errors

[Dan Mahoney]

> On May 31, 2023, at 12:25 PM, Petr Špaček <pspacek at isc.org> wrote:
> 
> On 31. 05. 23 18:08, E R wrote:
>> If you visit https://bind9.readthedocs.io/en/v9.18.15/ <https://bind9.readthedocs.io/en/v9.18.15/> you will see a menu in the lower left corner where you can select older releases of the bind ARM manual.  But those links do not work and return a 404.  Should those links work?  Or do they need to be removed?
> 
> The links from the menu I tried at random work for me. Which particular version is giving you trouble?
> 
>> In my case I visited https://kb.isc.org/docs/aa-01031 <https://kb.isc.org/docs/aa-01031> which pointed me to the right location to get a PDF copy of other releases and pointed me to the sources location where I can get the PDF that matches my distribution's version.
> 
> While reading you message I realized that we messed it up and old links with underscore (e.g. v9_18_10 as opposed to v9.18.10) indeed do not work.
> 
> I'll see if we can restore the old links, but I cannot promise any specific timeline.

Hey there FastEddie, I’m Dan with ISC’s SysAdmin team.  I normally work on the F-root side of the house and don’t usually chime in on bind-users, unless I’m working on mailman itself.

There are actually a couple of problems here, and I’d like to ask for your help, and that of the community.

First, there is the fact that (as Petr points out) at one point we had links with underscores versus dots.  We can fix those (when we know about them) by adding redirects inside ReadTheDocs (RTD, hereafter).  It’s tedious to create them for every iteration where vx_y_z does not exist but vx.y.z does, but that’s what might be necessary.  RTD is not smart enough to be told to “on 404, just jump to this version”, we have to create it for every version where this breakage happens.  We can create a custom 404 page, but not classic apache-style mod-rewrite redirects with wildcarding.

Second, I tried this with a version I had found on google: /en/v9_16_12/ and created a redirect to /en/v9.16.12/, which did exist inside ReadTheDocs, but that url was also 404ing because of a bad build due to a bad requirements.txt file.  So in that case, the best thing I could do was point the redirect at the oldest known *working* version of the docs (/en/v9.16.16/ in that case).  You’ll notice 9.12.16 doesn’t show up in the list of available doc trees on RTD.  Now, is there a lot of change delta between 9.16.12 and 9.16.16?  Probably not.  It’s better than handing out a 404.  This feels reasonable.

Finally, I realized that we’d like to be able to see what things out there in the world (and in Google’s caches) are referring to us, but because we don’t control the bind9.readthedocs.io domain, it’s a little harder to add it to our Google search console.  (Can’t put a CNAME record in, can’t upload an arbitrary .html file — and to add Meta tags, we’d have to do something “special” without adding that meta tag to ALL our docs).  RTD also doesn’t seem to give us server logs of what queries we’ve served up 404’s to.  We hope to fix that soon, but it’s not going to be instant.

===

I’m not sure if it’s a good use of engineer time to constantly be fixing failing-to-build versions of old documentation (like #2,  the 9.16.12 problem, above).  Creating the redirect solves the problem today, albeit in a slightly imperfect way, and we may be pushing fixes and/or creating redirects for stuff nobody’s actually linking to/reading.  (We’ll know that more when we solve #3)

So here’s where you (and others) can help with problem #3:  Please do report these if you see them!  I’m not sure if it’ll drive the bind9 folks crazy if you create gitlab issues, but do know we’ve seen this and we’re working on it.

Best,

-Dan