Docs release process improvement

[jimangel]

This issue is to track the overall process improvement of SIG Docs.

On Dec 6th 2019, @mrbobbytables opened up #956 to improve the docs release cycle using krel ff with a goal of being evaluated during the v1.18 cycle. However, after reviewing our options, it became clear that there needed to be a larger process change.

For historical context, docs release leads were given write access to k/website which was problematic and unnecessary. As a solution, the docs lead began working out of their respective forks to sync docs. This, in turn, created a larger problem where the docs lead needed k/website write access anyway to apply a specific label tide/merge-method-merge to their sync PR.

We can change the merge method of SIG Docs to use prow's defaults which will eliminate the need for applying a label with write access.

After that, we can begin to leverage release tooling like krel to fast-forward the dev-X.xY branches. If a merge conflicts appears, the lead could resolve manually and use krel to commit the change.

We can't automate a branch preference / default because sometimes you need to incorporate master commits, dev-X.xY commits, or a combination of both.

By using this approach, the docs release lead does not need write access until the actual release to merge and cut various release branches. To be honest, if the docs release process was 100% automated via krel, it could be done by a @kubernetes/release-engineering member.

Also, this release krel function can then be used for patch releases, release notes, and verisons to Kubernetes docs on k8s.io (currently unchanged until manual intervention).

This would allow the docs release team to focus on tracking, approving, and merging docs for the release.

TODO:

• Open a PR to change the merge strategy to not require the lead to use a label: Switch SIG Docs merge method from squash to merge (default) test-infra#16892
• Document squashing PRs in contrib guide
• Create a merge krel function that allows for syncing master and manual conflict resolution (/cc @saschagrunert)
• Create a release krel function that cuts, tags, and releases the Kubernetes docs.
• Integrate into the release cycle

To help with this process, I plan on assisting the 1.19 release team (/cc @onlydole) as a docs emeritus 😄 with the sole focus on removing human error and improving the handbook for future leads. (on going through 1.20)

Additional resources:

• https://jimsurls.com/git-branching/
• https://docs.google.com/document/d/1Y1u8IBfs5p9bQuUMxarltHoioMmuKybgtGL9U8tlO0E/edit?usp=sharing

/cc @zacharysarah @kbarnard10 @kbhawkey @sftim
/area release-eng
/kind feature
/priority important-longterm

[justaugustus]

/assign @jimangel

[sftim]

💭 SIG Docs has contributors who only work inside GitHub's web UI
If there were a Prow command /rebase-and-squash that does a rebase and squash, would that help those people?

[sftim]

(what I have in mind is that Prow force-pushes to your fork with the changes, and you have to select the option to allow maintainers to make edits).

The idea here is that someone with zero command line experience can get their PR squashed. I won't expect Prow to resolve every possible conflict, and I don't expect this will work as well for Go code as it does for Markdown.

[celestehorgan]

@jimangel

After assessing the kubernetes/communtiy repo, the following pages currently mention squashing before a merge:

• GitHub Workflow
• Pull Requests
• Contributor Cheatsheet

I suggest the following:

• Update GitHub Workflow with more comprehensive instructions on how to pull off a squash
• Update the Contributor Cheatsheet with similar.

I suggest we also add something similar to Work from a local clone. (Note that I'm also in the middle of a big cleanup of this section, so I'll add changes to that PR as well.)

---

This runs into a bigger issue re: duplication inkubernetes/community and the docs website. Zach wrote about it a year ago https://github.com/kubernetes/website/issues/14101.

For now I think we need to accept a bit of duplication, but it's something to keep an eye on.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale