github-management: add docs for master to main migration

This document is meant to be used by repos without too much traffic,
if they wish to migrate the default branch from master to main.

1 files changed, 134 insertions, 0 deletions

diff --git a/github-management/default-branch-migration.md b/github-management/default-branch-migration.md
new file mode 100644
index 00000000..7740c8c0
--- /dev/null
+++ b/github-management/default-branch-migration.md
@@ -0,0 +1,134 @@
+---
+title: Default Branch Migration
+linkTitle: Default Branch Migration
+description:  |
+  Instructions on how to migrate the default branch from master to main.
+weight: 99
+type: docs
+aliases: [ "/rename" ]
+---
+
+# Default Branch Migration
+
+This document outlines steps needed to migrate the default branch
+of your repo from `master` to `main`.
+
+Note: This document is currently a work in progress.
+
+If you have questions about the process, reach out to the GitHub Management Team
+on the [#github-management] channel on slack or open an issue in the [kubernetes/org] repo.
+
+## 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.
+
+- [ ] If you are not a root approver for the repo, assign a root
+approver for approval.
+
+- [ ] Once the issue has been approved, send a notice to your SIG's
+mailing list about the potential branch rename.
+
+## Changes pre-rename
+
+Make the following changes _before_ renaming the branch the `master` branch.
+
+Note: There might be additional changes required that have not been
+covered in this checklist.
+
+### Anytime
+
+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 the [`milestone_applier`] prow config references the `master` branch,
+add the `main` branch to the config (see [kubernetes/test-infra#20675] for an example).
+
+- [ ] If the [`branch_protection`] prow config references the `master` branch,
+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.
+
+- [ ] If a prowjob calls scripts or code in your repo that explicitly
+reference `master`, update all references to use `main`.
+
+- [ ] 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.
+It can't be controlled through the netlify config in the repo.
+
+### Approval
+
+- [ ] Once all non-disruptive tasks have been completed and disruptive tasks
+have been identified, assign the GitHub Management team ([@kubernetes/owners])
+for approval.
+
+## Rename the default branch
+
+- [ ] Rename the default branch from `master` to `main` using the GitHub UI
+by following the [official instructions].
+
+## Changes post-rename
+
+After the default branch has been renamed to `main`, make the following
+changes.
+
+Note: There might be additional changes required that have not been
+covered in this checklist.
+
+### Prowjobs
+
+- [ ] If a prowjob still references the `master` branch in the `branches` field,
+remove the `master` branch (see [kubernetes/test-infra#20669] for an example).
+
+### Prow config
+
+- [ ] If the [`milestone_applier`] prow config references the `master` branch,
+remove it from the config.
+
+- [ ] If the [`branch_protection`] prow config references the `master` branch,
+remove it from the config.
+
+### Other
+
+- [ ] If any docs reference the `master` branch, update to `main`
+(URLs will be automatically redirected).
+
+- [ ] Ensure that CI and PR tests work fine.
+
+- [ ] Trial the local development experience with a pre-rename clone.
+
+- [ ] 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].
+
+[kubernetes/org]: https://github.com/kubernetes/org/issues
+[@kubernetes/owners]: https://github.com/orgs/kubernetes/teams/owners
+[#github-management]: https://kubernetes.slack.com/messages/github-management
+[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#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
+[`milestone_applier`]: https://github.com/kubernetes/test-infra/blob/ca6273046b355d38eade4c4bd435bd13fbb55043/config/prow/plugins.yaml#L324
+[official instructions]: https://github.com/github/renaming#renaming-existing-branches
+[GitHub instructions to rename your local branch]: https://docs.github.com/en/github/administering-a-repository/renaming-a-branch#updating-a-local-clone-after-a-branch-name-changes