Ensure doc.crds.dev is updated on new release

[cahillsf]

Part of Improvement tasks for v1.6 release cycle #9104

automate updates to specific versions of https://doc.crds.dev/github.com/kubernetes-sigs/cluster-api after release is cut
the link: https://doc.crds.dev/github.com/kubernetes-sigs/cluster-api@latest needs to be called at least once before it's cached as the base page for the repo. The idea is to automate that update - we could initially document checking that page as a task during the release process manually. Automation can also be considered, i.e the same way how it is done in https://github.com/oracle/cluster-api-provider-oci/blob/main/.github/workflows/release.yaml#L28-L31

There is discussion in the umbrella issue regarding whether automation is worth the maintenance effort. As a first step we will document that this link needs to be called after the release has been cut, and continue discussing tradeoffs for pursuing automation if needed.

• document that the new release tag link needs to be accessed in order to index the updated tag
• attempt to address the latest tag behavior when no tag is provided in the URL params
  • FR opened here
  • open a PR - WIP

/kind documentation
/area release

[cahillsf]

/assign cahillsf

[sbueringer]

/triage accepted

[cahillsf]

as a related issue, we have this issue with the docs page:

I do not why, but when I click the above link, I have list of CRDs from v1.4.5, should we change it to point to latest?

I get the same, I have no idea

After further investigation, it appears that the default tag to be served if not provided in the URL params will be based on the time column of the tags in the database (src). Running a local instance of this app, I have evidence that the time is based off of the most recent push to the tag

For example v.1.5.0 in my local db: https://a.cl.ly/qGu6e4oY

Corresponds to the most recent push GH link: screenshot

This means that in order to consistently serve the true latest tag as the default we will either need to:

• ensure that when backporting from main, the most recent tag is updated last - in this case v1.4.5 was updated more recently than v1.5.0
• update the logic in select statement to sort by name rather than time

[sbueringer]

I think ideally they should serve the latest release as latest (or the one with the highest semver)

[furkatgofurov7]

• ensure that when backporting from main, the most recent tag is updated last - in this case v1.4.5 was updated more recently than v1.5.0

Thanks for digging into this, and finding out a reasoning behind it.

I believe we can't always make sure backporting is done to the latest tag at last IMO, so ideally I would fall into the second option and try to update the logic in the crdsdev/doc repo itself

[furkatgofurov7]

/priority important-soon