Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
holly-cummins opened this issue Apr 17, 2023 · 1 comment

Comments

@holly-cummins
Copy link
Contributor

holly-cummins commented Apr 17, 2023

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

The root problem is a mismatch in the release cadence of the documentation web pages and the individual extensions. As discussed in quarkusio/quarkus#31148 and quarkusio/extensions#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, quarkusio/quarkus-extension-catalog#52.)

@holly-cummins holly-cummins changed the title Avoid serving dead guides links caused by shifts in what 'latest' points to Correct dead guides links caused by shifts in what 'latest' points to Apr 17, 2023
@holly-cummins holly-cummins changed the title Correct dead guides links caused by shifts in what 'latest' points to Auto-correct dead guides links caused by shifts in what 'latest' points to Apr 17, 2023
@holly-cummins
Copy link
Contributor Author

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."

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant