docs: update default-branch-migration.md

specifically

- remove reference to prow retriggering presubmits on PR rename (thanks
for the fix GitHub! :heart:)
- add links to issues for bootstrap and pod-utils not supporting default
branch as a concept
- add snippets showing how to auto-detect remote branch
- misc rewording or rephrasing

1 files changed, 48 insertions, 21 deletions

diff --git a/github-management/default-branch-migration.md b/github-management/default-branch-migration.md
index e6ff642e..e37b96c4 100644
--- a/github-management/default-branch-migration.md
+++ b/github-management/default-branch-migration.md
@@ -20,10 +20,6 @@ on the [#github-management] channel on slack or open an issue in the [kubernetes
 
 ## Prerequisites
 
-- [ ] Ensure that your repo has low PR volume (<20 open PRs) and
-less number of periodic jobs. The branch rename will re-trigger
-prow on _all_ open PRs, which will cause a huge spike in the CI load.
-
 - [ ] Create an issue in your repo to track the branch rename.
 You can paste this checklist in the issue body.
 
@@ -42,12 +38,12 @@ covered in this checklist.
 
 ### Anytime
 
-These changes are **non-disruptive**  and can be made anytime before
-renaming the branch.
+These changes are **non-disruptive**  and can be made anytime before renaming
+the branch.
 
-- [ ] If a prowjob triggers on the `master` branch (`branches` field
-of the prowjob), add the `main` branch to the list
-(see [kubernetes/test-infra#20665] for an example).
+- [ ] If a presubmit or postsubmit prowjob triggers on the `master` branch
+  (`branches` field of the prowjob), add the `main` branch to the list
+  (see [kubernetes/test-infra#20665] for an example).
 
 - [ ] If the [`milestone_applier`] prow config references the `master` branch,
 add the `main` branch to the config (see [kubernetes/test-infra#20675] for an example).
@@ -57,20 +53,45 @@ add the `main` branch to the config.
 
 ### Just before rename
 
-These changes are **disruptive** and should be made just before
-renaming the branch.
-
-- [ ] If a prowjob mentions the `master` branch in `base_ref`,
-update it to the `main` branch. For a periodic job, ensure that
-the branch is renamed between periodic job runs.
-
-- [ ] If a prowjob mentions `master` in its name, rename the job to
-to not include the branch name. [`status-reconciler`] should automatically
-migrate the PR status contexts to the new job name but this has not been tested yet.
-The job with the new name will also appear as a differt job in Testgrid.
+These changes are **disruptive** and should be made just before renaming the
+branch.
+
+- [ ] For periodic prowjobs, or any prowjob that mentions the `master` branch
+in `base_ref`, update them to the `main` branch. Ensure that these changes
+happen in lock-step with the branch rename (jobs triggered in between landing
+these changes and renaming the branch will fail).
+  - For bootstrap-based jobs, ensure the branch is explicitly specified,
+    e.g. `kubernetes/foo=main`. [kubernetes/test-infra#20667] may eventually
+    allow for non-disruptive changes.
+  - For pod-utils based jobs, ensure the branch is explicitly specified,
+    e.g. `base_ref: main`. [kubernetes/test-infra#20672] may eventually allow
+    for non-disruptive changes.
+
+- [ ] If a prowjob mentions `master` in its name, rename the job to not include
+the branch name, e.g. `pull-repo-verify-master` -> `pull-repo-verify`.
+[`status-reconciler`] should automatically migrate PR status contexts to the
+new job name, and retrigger accordingly, but we have anecdotally found it
+sometimes misses changes.
+  - NOTE: our infrastructure doesn't understand the concept of job renames, so
+  from the perspective of e.g. https://testgrid.k8s.io the job will appear to
+  have lost history and start from scratch.
 
 - [ ] If a prowjob calls scripts or code in your repo that explicitly
-reference `master`, update all references to use `main`.
+reference `master`, update all references to use `main`, or auto-detect the
+remote branch
+  - e.g. using git to auto-detect
+  ```sh
+  # for existing clones, update their view of the remote
+  git fetch origin
+  git remote set-head origin -a
+  # for new clones, or those updated as above, this prints "main" post-rename
+  echo $(git symbolic-ref refs/remotes/origin/HEAD)
+  ```
+  - e.g. using github's api to auto-detect
+  ```sh
+  # gh is https://github.com/cli/cli, this will print "main" post-rename
+  gh api /repos/kubernetes-sigs/slack-infra | jq -r .default_branch
+  ```
 
 - [ ] If the repo has netlify configured for it, ask a member of the GitHub
 Management Team to rename the `master` branch to `main` in the netlify site config.
@@ -114,8 +135,13 @@ remove it from the config.
 (URLs will be automatically redirected).
 
 - [ ] Ensure that CI and PR tests work fine.
+  - If there are any outstanding PRs you can /approve to merge, do so to verify
+  that presubmits and postsubmits work as expected
 
 - [ ] Trial the local development experience with a pre-rename clone.
+  - ensure [Github instructions to rename your local branch] work
+  - consider updating your fork's default remote branch name such that if you
+  have git autocompletion enabled, typing `ma<tab>` will autocomplete to `main`
 
 - [ ] Send a notice about the branch rename to your SIG's mailing list.
 Include the link to the [GitHub instructions to rename your local branch].
@@ -126,6 +152,7 @@ Include the link to the [GitHub instructions to rename your local branch].
 [kubernetes/test-infra#20665]: https://github.com/kubernetes/test-infra/pull/20665
 [kubernetes/test-infra#20667]: https://github.com/kubernetes/test-infra/issues/20667
 [kubernetes/test-infra#20669]: https://github.com/kubernetes/test-infra/pull/20669
+[kubernetes/test-infra#20672]: https://github.com/kubernetes/test-infra/issues/20672
 [kubernetes/test-infra#20675]: https://github.com/kubernetes/test-infra/pull/20675
 [`status-reconciler`]: https://github.com/kubernetes/test-infra/tree/master/prow/cmd/status-reconciler
 [`branch_protection`]: https://github.com/kubernetes/test-infra/blob/ca6273046b355d38eade4c4bd435bd13fbb55043/config/prow/config.yaml#L131