Documentation on readthedocs - links to older releases return 404 errors

[Andrew Latham]

Issues can be tracked at https://gitlab.isc.org/isc-projects/bind9/-/issues
if it helps

On Wed, May 31, 2023 at 3:46 PM Dan Mahoney <dmahoney at isc.org> wrote:

>
>
> > 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
> --
> Visit https://lists.isc.org/mailman/listinfo/bind-users to unsubscribe
> from this list
>
> ISC funds the development of this software with paid support
> subscriptions. Contact us at https://www.isc.org/contact/ for more
> information.
>
>
> bind-users mailing list
> bind-users at lists.isc.org
> https://lists.isc.org/mailman/listinfo/bind-users
>


-- 
- Andrew "lathama" Latham -
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.isc.org/pipermail/bind-users/attachments/20230531/855bb8d6/attachment-0001.htm>