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

[cahillsf]

I see you found this issue as well Stefan. Seems unlikely that opening an issue to address this behavior will get prioritized.

Also it looks like this option would not work anyway:

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

It seems that once the tag has been initially indexed, the time will not be updated as it will only reindex tags it has not seen before (src).

I can take a shot at opening a PR to sort by semver tag, although it does seem like the future of this tool is uncertain. What do you think @sbueringer @furkatgofurov7 ?

Looks like Joe went ahead and just added the CRD references to their book rather than relying on the tool, so maybe this is a better path to invest time in?

[sbueringer]

I would probably continue to use docs.crds.dev if our only problem right now is the tag thing. We can always start generating the docs ourselves if it should go away.

Not sure if we should move ahead of time. I prefer the way that docs.crds.dev renders it.

[furkatgofurov7]

I think giving a shot to change the current behavior in crdsdev/doc would be a first option considering it is not yet fully clear if the project will go away. If the change is rejected/can't be made or worst case project is taken down, we can re-evaluate and see other options like generating them ourselves at last.

[cahillsf]

Repo maintainer is not responding on the improvement to the tags behavior (have a FR and a draft PR - opened 4 months ago and bumped with no reply).

Going to close this out.