Auto-correct dead guides links caused by shifts in what 'latest' points to

[holly-cummins]

There are several points in an extension's lifecycle when its guide link might be invalid, and it's not the extension's "fault".

• An extension has been newly released, but isn't in a platform release yet, so only main/guides links work, not the preferred guides links. See, for example, https://github.com/quarkusio/quarkus/issues/31148.
• An extension isn't available in the latest release of a platform, but is still available in earlier releases. Links with latest in them will be broken by the new release. For example, https://camel.apache.org/camel-quarkus/latest/reference/extensions/smallrye-reactive-messaging.html stopped existing when the Camel Quarkus 3 release was done.

The root problem is a mismatch in the release cadence of the documentation web pages and the individual extensions. As discussed in https://github.com/quarkusio/quarkus/issues/31148 and https://github.com/quarkusio/extensions/issues/155, it's not practical to change guide links in extensions on the exact same cadence as the web pages change. Instead, we can do some pragmatic adjustments to links:

• If a link doesn't exist in guides but does exist in latest/guides, link to that
• If a link doesn't exist in latest but does exist in an earlier version, link to that

I resolved this for the extensions page with #196. However, @maxandersen points out that this doesn't help any of the other consumers of the registry, so we should port this change to the central registry.

Implementation

I think this needs to be done either as a nightly job, or as a transparent rewrite before serving data on endpoints. It needs URL lookups, which can be slow, so a nightly job might be best.

We can't do it on upload, because that doesn't catch the case where an external link changes 'after' the extension has been released.

We should rewrite the guides link to a correct one, not just drop it.

Deprecated extensions

There's a third case where extensions may have dead links, which is that they're deprecated. In the extensions UI, I auto-hide dead links in deprecated extensions, so we could consider porting that change, too.

(Sometimes an extension has been deprecated, but no release with deprecated status was made. Since the extension is deprecated, the docs pages have been taken down. It would be a lot of effort to do a special release of the extension just to update the status. We have added the ability to patch extensions in the registry to add a deprecated status. See, for example, https://github.com/quarkusio/quarkus-extension-catalog/pull/52.)

[holly-cummins]

We may want to make a more significant change as part of this work item.

@maxandersen points out "we really need to find another way for extensions to point to docs beyond "latest" if we can't keep urls working. actually even if we can keep it and the link is there...its not the right one for older extensions."

And I added "I think the ideal state is that in the source control the guides link is fairly generic (specify a domain, specify a page name) and then in the registry it's mapped to one which is specific for that version.

At the moment we don't see the problem tooo badly because we only expose the latest extension, so a 'latest' link is ok, most of the time (but not always). At some point we'll start exposing other versions and then the guides links will be wrong for the older ones."