Automatically verify links from documentation to our GitHub issues

[marians]

We set links from documentation content to GitHub issues, usually to provide more information about a planned feature or a change in progress.

As of May 2024, we have 173 links to https://github.com/giantswarm/* in our docs content (excluding /changes).

This sort of information usually gets outdated at some point. The feature described in the issue might be implemented, the change might be done. Usually the issue gets closed. Often, the required change in the referring documentation part is forgotten.

Example

Here is a proposal on how to tackle this problem:

• We create a script that crawls all links to Github issues (in the giantswarm organization at least). If the linked issue is closed, a warning is emitted.
• We introduce a HUGO shortcode to allow for more expressiveness, e. g. to allow linking to a closed issue without emitting such warning. Example: {{ github_issue repo="giantswarm/roadmap" state="closed" }}.
• Once an issue gets closed, we check docs references to the issue and add a comment to the closed issue, informing about the reference and the need to check for content up-to-dateness.

This linter could potentially even function without GitHub API credentials, as all linked issues should be public and issue state should be accessible via the public API.

Example query for #103 :

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/giantswarm/roadmap/issues/103

[AndiDog]

I would avoid putting any "future plans" into documentation, with maybe very few exceptions. Changelogs provide major updates and new features, and progress on new development is typically communicated directly with customers. As this issue says, those links get 100% outdated or invalid very soon, and it's unrealistic for the author to come back to a documentation page – those pages are usually written/rewritten at most once a year, and not revised in that detail on a regular basis.

[lyind]

Why would one remove links to old issues?

I have often used such to retrace what lead to certain decisions being taken or designs implemented. Why take that away?

[pipo02mix]

I am in favour of not adding roadmap issues to our documentation. For current customers we can directly provide them with a way to follow the progress, we have an open Github Roadmap board that anyone can view and it could be mentioned on our support page to explain how we work, but I don't see value to link to GH issues in regular doc entries. I am happy to remove those during the revamp, WDYT?

[marians]

@AndiDog The problem you describe is exactly the one I'm trying to address.

@lyind The proposal is not necessarily about removing a link. It's about getting notified if a linked issue gets closed, as this might be a good occasion to review the reference.