General instructions to proceed to move from master to main

master2main.md

⚠️ NOTE
The content of this gist has been moved to Moodle Dev Docs. Please, go there to get the latest version.

This tries to, briefly, show all the changes required to rename any branch from "master" to "main" in general. Aimed for the Moodle Community, to facilitate the transitions of all their awesome patches, plugins and integration, although, generic enough for anybody needing to rename any branch.

Moving from "master" to "main" for canonical/origin github based repositories

Note that these steps are valid for all the repositories @ GitHub. That includes both the "cannonical/origin/upstream" ones and, also, all the clones of them that any developer/contributor may have.

1. Go to your repo, click on "Settings"
2. In the "General" settings page, near "Default branch" click on the pencil icon.
3. Rename "master" to "main" (all associated pull requests will be migrated, also any protection ruless and other bits. See https://github.com/github/renaming for more information.
4. Time to hack (see the section)

Moving from "master" to "main" for other canonical/origin (gitlab, bitbucket, sourceforge, ...) repositories

1. Check if the repo supports renaming branches (similar to GitHub) or no. And verify if the utility allows the old "master" to continue working and if associated pull/merge requests and other settings are automatically moved or no.
2. If the rename utility exists and suits your needs, use it (and skip next point).
3. In general, if there isn't any rename tool, the way to proceed manually is to:

   1. Fetch all changes from remote and ensure that "master" is up to date.

      git fetch --all --prune && git fetch origin master:master

   2. Create locally the "main" branch from "master".

      git branch main master

   3. Push the new branch upstream.

      git push origin main

   4. In the canonical repo, configure everything to point to the new "main" branch (rules, default branch...). Don't forget to analyse what happens with ongoing pull/merge requests that may be pointing to "master".

   5. Once 100% sure that "main" is ok, remove the, now old, "master" branch.

      git push origin :master

   6. It's recommended to create a new issue in the repository (link to example), explaining the move from "master" to "main", so everybody that is subscribed or involved gets notified. Feel free to point to this document for details.

4. Time to hack (see the section)

Time to hack

Let's move any "master" occurrence/dependency in the codebase to "main" (link to example).

1. For sure that includes any Travis/GHA... CI integrations. And any other external tool (codecov, packagist...) that is being used.
2. If your codebase has any other hard-coded "master" dependency (not the best idea, but) ... it will need to be analysed and fixed too.
3. Apply changes (push, PR/MR, whatever...) ASAP.
4. ...

Moving from master to "main" in your local clones

1. Fetch all changes from remote (that has been just renamed upstream).

   git fetch --all --prune

2. Rename the local branch from "master" to "main".

   git branch -m master main

3. Point the local "main" branch to the remote "main" one (assuming that the canonical remote is named "origin" in your clone).

   git branch -u origin/main main

4. Adjust your local current HEAD, that still is pointing to the, now gone, "master" branch.

   git remote set-head origin -a

5. Verify that your local clone looks ok (so you can check your actual local branches and which remote/branch they are tracking now).

   git branch -vvv