Rename master branch

[billsacks]

The master term can be offensive, and so GitHub and others are encouraging switching to a more neutral term. main seems to be a good choice; some others would be latest, trunk, stable or develop. It sounds like GitHub will be publishing guidance on how to accomplish this soon. Otherwise, a quick search turned up these recent guides:

https://dev.to/rhymu8354/git-renaming-the-master-branch-137b

https://www.hanselman.com/blog/EasilyRenameYourGitDefaultBranchFromMasterToMain.aspx

I'm calling this a "documentation" issue because the pieces needed are probably more on the documentation side than anywhere else, and I don't think this will require any actual code changes.

---

Update (2021-03-08)

Here are the steps I can think of. I think we should do them in this order:

• Change documentation: rename master to main
  • wiki (start by reverting commit 443e84d, but there may be more to do than that)
  • any README files that reference master
  • any mentions of master in doc/source
• Rename branch on GitHub
• Send instructions to developers (see Rename master branch #1048 (comment))
  • Relevant email list(s) (just ctsm-dev)
  • Message the ctsm team on GitHub

[billsacks]

@ckoven thanks for suggesting this idea on the FATES side.

[wwieder]

Yep, let's make this move & make the transition as smooth as possible for cloned repos.

[billsacks]

https://github.com/github/renaming

[ekluzek]

As part of this we should also change our documentation (README files and the like) that refer to the master branch. Also likely in our wiki pages as well.

github.com is making this change for all projects on Oct/1/2020.

[rgknox]

I was reading the second guide you posted @billsacks , thanks.
It seems like this will only require two commands to make the change.

[ekluzek]

I think github.com has done all of the changes they plan to implement to help this change. They make it easy on the web-interface, and it automatically forwards branch protections and even lets people know about the change on a "push". The web-interface also lets you know what you need to do. When you go to your fork it does for example point out that you need to change it. And the first time you go to a repository with the change there's a pop up that tells you about the change.

Clones and forks do have to change. The commands for us in git on a clone are like this (github also tells you about the need to do this)...

git branch -m master main
git fetch escomp
git branch -u escomp/main main

(Note the details of above does depend on how you have named your remotes, this assumes you use the escomp convention)

I've done this in PTCLM, just to see how easy it was and what had to be done.

[billsacks]

Awesome, thanks @ekluzek for looking into this more. I have edited the top-level comment to put a checklist of things I can think of that need to be done. Feel free to edit it and add anything else you can think of.

[wwieder]

Is this something we need to help communicate to model users / developers, or can new forks & PRs just merge these changes without too much disruption?