SIG Docs Tech Leads to learn/document reference docs generation process for a Kubernetes release
natalisucks opened this issue · comments
What would you like to be added:
During the v1.30 Release Docs Team retro, facilitated by SIG Docs, we spoke about the opaqueness of the reference docs generation process, which has been continuously opaque for releases from around 1.21/1.22 onwards. Instructions in the Release Docs handbook were incomplete up until recently being completely removed. Release Team subproject leads AND SIG Docs leads want the Release Docs team to be able to execute on this work as part of their Release Team duties in the future.
What we need, at minimum, is for the process to be documented so that any Release or SIG Docs lead can undertake this task.
The timing of reference docs generation is always after the release goes out, as they cannot be generated until the release tag exists (likely several hours later). For each release, the generator must be adapted accordingly, which is done purely by @tengqm at present (we are currently looking for more maintainers of the SIG Docs reference-docs subproject in parallel). The update to the go.mod file is an manual step. At present, Qiming adapts the generators for the new release and proposes PRs directly to the website repo. Generating the references during adaptation takes place in parallel, which is a "simple" way to describe the current process.
Why is this needed:
We currently rely on the knowledge of only a few people to generate our reference documentation each release (specifically Qiming, Rey, and Nate Waddington). We need all current SIG Docs Tech Leads and Release Team subproject owners to learn and create the required docuemntation.
For release v1.31, we will have Kat, Xander, Rey, and Nate work together on learning this work and creating a first pass at documenting the process. After, one of the SIG Docs Tech Leads will co-lead the reference-docs subproject alongside Qiming to help maintain the tooling and to recruit further contributors for future automation and improvements to the subproject.
/cc @reylejano @divya-mohan0209 @tengqm @katcosgrove @salaxander
/triage accepted
/priority important-soon
At present, Qiming adapts the generators for the new release and proposes PRs directly to the website repo. Generating the references during adaptation takes place in parallel, which is a "simple" way to describe the current process.
I think @feloy has also worked on reference docs changes that relate to https://kubernetes.io/docs/reference/kubernetes-api/
(As far as I know) we don't have a documented process for updating https://kubernetes.io/docs/reference/kubernetes-api/ once a new release is imminent.
I have a process improvement suggestion.
At code freeze, could we update the dev branch for the upcoming release with interim docs, and then do a post-release PR to cover any API or tool updates that landed during code freeze?
We could potentially add a Prow command or similar tooling to automate part of this. @dims helped make some similar automation for k/k updates.
At present, Qiming adapts the generators for the new release and proposes PRs directly to the website repo. Generating the references during adaptation takes place in parallel, which is a "simple" way to describe the current process.
I think @feloy has also worked on reference docs changes that relate to https://kubernetes.io/docs/reference/kubernetes-api/
Right, I've maintained this documentation for releases v1.22 to v1.28. Due to other engagement, I have not been able to update it for the last two releases.
(As far as I know) we don't have a documented process for updating https://kubernetes.io/docs/reference/kubernetes-api/ once a new release is imminent.
The process is concisely described at: https://github.com/kubernetes/website/blob/main/README.md#building-the-api-reference-pages
The point 3/ of the documentation is probably the one needing some knowledge of how the generator works / some experience. I proposed a few releases ago to have some live call with docs maintainers to make some "pair programming" together, to be able to share this knowledge. My proposition is still valid.
For these changes, you don't particularly need the tag to exist. You just need to be confident that the swagger file, on which the generation relies, won't be changed afterwards.
The API reference generator takes the swagger file as its input. There is no dependency upon other kubernetes repos. Once we are confident that swagger file won't change, the reference page can be generated prior to a release.
However, all other reference generators depend on the existence of git tags which are only available when a new release is cut. Generating interim docs may complicate the whole process for no good I'm aware of.