Choosing a different default branch name than master

[Mr0grog]

One thing that’s come up recently in some software development fora is renaming the default branch in Git repositories from “master” to something else (“master” actually doesn’t mean anything special in Git — it’s just the default chosen when you run git init — so you are always free to choose a different name for your default/main/primary/base branch).

Unfortunately, it’s pretty early for this, so there doesn’t seem to be an especially clear consensus on an ideal alternative name. Some I’ve seen or that make a lot of sense:

• “main” (pretty self-explanatory; same first two characters as “master,” so if you love tab completion, this might be like nothing changed at all for you)
• “latest” (pretty self-explanatory; used by the git-the-latest NPM module)
• “trunk” (old-school folks will remember this as Subversion’s default branch name)
• “primary”
• “default” (the default branch name in Mercurial)
• “base”
• (Any other good suggestions?)

I prefer and recommend “main.”

I’d love to know whether others have any particular thoughts on whether this would be a good idea, and what a good name would be.

While it’s a small gesture, it seems to me that making some change, at least for new repositories, is pretty easy and worthwhile (we’d update the template repository and add a not in repo_guidelines.md). BUT if folks think it’s better to let this lie for a while and see what starts to shake out as a common name, that’s also OK.

Should we also update existing repositories? That’s messier, and a little more intensive.

/cc @Frijol @lightandluck @danielballan @shansen5 @ericnost

[ericnost]

I had been thinking about this recently and had settled on "main" as well. I believe new repositories should use "main", but I don't really understand what it would take to update existing repos so I can't comment there. Would we have to create a new branch called "main" and then update the default branch from "master" to "main"? I know how to do this in GitHub but not Git.

Would it break code anywhere? For instance, we would need to update the Colab links to our Jupyter Notebooks from e.g. colab.research.google.com/github/edgi-govdata-archiving/ECHO-Cross-Program/blob/master/facility-all-programs.ipynb to colab.research.google.com/github/edgi-govdata-archiving/ECHO-Cross-Program/blob/main/facility-all-programs.ipynb

[Mr0grog]

I don't really understand what it would take to update existing repos so I can't comment there. Would we have to create a new branch called "main" and then update the default branch from "master" to "main"?

Pretty much (but don’t forget to delete “master” on the GitHub side at the end).

The complexity I’d worry about here isn’t really technical — it’s more the human fuzziness of everyone using the repo needs to update their local copies and/or forks, remember to stop using “master” on their end, etc. (The downside of git being distributed! Everyone’s forks and local copies are independent repos.)

For instance, we would need to update the Colab links to our Jupyter Notebooks from e.g. colab.research.google.com/github/edgi-govdata-archiving/ECHO-Cross-Program/blob/master/facility-all-programs.ipynb to colab.research.google.com/github/edgi-govdata-archiving/ECHO-Cross-Program/blob/main/facility-all-programs.ipynb

Oh, yeah, links from other places could definitely break. 😬

(Side note: anywhere you don’t need a link to the latest version of a thing, it’s almost always a good idea to to the commit hash instead of the branch, for exactly this reason. e.g. https://github.com/edgi-govdata-archiving/ECHO-Cross-Program/blob/a821eeb8724aafdab07d957f07df5da763f697db/facility-all-programs.ipynb Unfortunately, GitHub doesn’t always make getting that link easy.)

[patcon]

Seems like a nice & easy gesture. I support this! +1 to main.

I wanted to ack that someone can recognize git's alternate origin, however remote (*cough*) -- more like "masterpiece" or "master recording", rather than "master-slave" paradigm of databases -- and still support this change. Just because words have meaning outside a racialized context, that doesn't mean we have to choose to lean on them for our newer concepts :)

Oh, yeah, links from other places could definitely break.

Could leave it there, but just switch default branch to new main -- the digital equivalent of putting master branch in a museum. Or a river ;)

[Mr0grog]

I wanted to ack that someone can recognize git's alternate origin, however remote (cough) -- more like "masterpiece" or "master recording", rather than "master-slave" paradigm of databases -- and still support this change.

Agree! Although, super interesting note… the “master” in git is about “master/slave,” not “master copy:” https://mail.gnome.org/archives/desktop-devel-list/2019-May/msg00066.html (I only found this the other day because I also had the exact same thought as you here, but was curious if I was assuming correctly about the history.)

Oh, yeah, links from other places could definitely break.

Could leave it there, but just switch default branch to new main

We could. I worry it would lead to maximum confusion for someone who didn’t read this issue discussion, though.

the digital equivalent of putting master branch in a museum. Or a river ;)

🤣

[patcon]

I worry it would lead to maximum confusion for someone who didn’t read this issue discussion, though.

Thought experiments:

1. Keep unused branch. Any confusion will be from someone cloning project and working locally.
   • What will that person do next? Will they likely be in a position to be supported by a "resident human" on the project?
2. Delete unused branch. Any confusion will be from someone clicking links and finding 404s.
   • What will that person do next? Will they likely be in a position to be supported by a "resident human" on the project?

To me, (2) feels like much more inconvenience to people less likely able to remedy the situation. It will be experienced by people just passing through or finding links scattered around the internet. A person experiencing (1) will be closer to the project, likely willing to put in more effort, and will be around ppl who can easily answer and support them :)

For me personally, de-emphasizing/hiding the master branch (but not deleting) feels like the right balance. 😸

[Frijol]

+1 to all this!

Heads up to @lourdesvera that upon implementation of this change in the EEW notebooks all the links to the colabs would change – are they linked to anywhere other than the EEW Tracking spreadsheet and the Congressional District primer? (Updating these links in a thorough way would likely be the most challenging aspect of this change at the moment, but this is a good moment to do it as we haven't really kicked the EEW project into full gear yet)

[Mr0grog]

Keep unused branch. Any confusion will be from someone cloning project and working locally.

The other kind of confusion I foresee with this is: a month or more after the change, someone clicks a link that works, but leads to code that is way out of date without any clear indicators that’s the case. (Best case, it’s just old code/documentation; worst case, it’s totally broken code/inaccurate documentation. In either case, it has similar broad impacts to the broken link problem from point 2, but the brokenness is not obvious.)

BUT! Maybe putting a big notice in the README on the master branch is a good enough hint to soften that problem? It’s far from perfect (someone linking directly to a Jupyter/Colab notebook like above won’t see it), but at least is something.

[patcon]

Ah good point! Or maybe add a final commit to master that changes every file to a simple link to the new place. (could even make reference to the rationale, so that it's not a silent swap, but a mild moment of enlightenment)

[Frijol]

Biggest failure mode I'd expect is someone thoughtlessly pushing to master instead of main, in which having links in the files wouldn't work. (I mean, one should pull request, but EDGI doesn't have a great track record on this)

Is there a way to explicitly archive the branch in github/git so it doesn't accept new commits?

[Mr0grog]

Oh, yeah, we can protect the branch so you can’t push to the copy in GitHub. See the branch settings page, e.g: https://github.com/edgi-govdata-archiving/overview/settings/branches

[Mr0grog]

(Has to be done on each repo, though.)

[Mr0grog]

Did some testing on template repos. The default branch applies to the new repo (yay!), but branch protection rules do not come along for the ride (even if you check “include all branches”). So we might leave the master branch in other existing repos, but I think we should remove it from the template repo.

As far as branch names, it seems like everyone likes “main,” so I’ll file PRs to update instructions and update the template repo.

[patcon]

"master"

*main :)

[Mr0grog]

Ugh, fixed! 😅

[lightandluck]

I like main as well =)

So, sounds like to transition old repos we would need to:

1. Create a new main branch from master
2. Fix links where we can.
3. Create a final commit in master with a message in the README explaining the switch over
4. Make the main branch the default branch in the settings
5. Put lots of restrictions on the master branch as a reminder not to work on it going forward

Is that right? Anything else?

I can create an issue and checklist and begin working on transitioning next week, when we agree to steps.

[patcon]

Is that right? Anything else?

If the only reason we're leaving master around is to help the click-through ppl, then there's maybe no purpose to any of the files on master except pointing ppl in the right direction. If so, then why stop at the README, when we could just change all files into pointers :)

Running this should iterate through all files in git, and point them to their new equivalents on the new branch, if that's what we want to do -- I don't have a strong opinion, just wanted to make it easy :)

Run this oneliner from the root of any repo, with adjustments for repo name:

git ls-files | xargs -E $'\n' sh -c 'for arg do echo "This file has moved to https://github.com/edgi-govdata-archiving/overview/tree/main/$arg." > $arg; done'

[Mr0grog]

If the only reason we're leaving master around is to help the click-through ppl, then there's maybe no purpose to any of the files on master except pointing ppl in the right direction. If so, then why stop at the README, when we could just change all files into pointers :)

I think that might be problematic for things that aren’t linking for the purpose of web browsing, e.g. the Google Colab notebooks @ericnost mentioned above would break if we did that: #241 (comment)

[Frijol]

making sure @maalvikabhat also sees this is going on as it may have ramifications for EEW notebook links

[maalvikabhat]

thank you so much

[lightandluck]

Yea, I wouldn't want to edit all files in case it breaks something.

If there's no other objections or concerns, I'll start working on the steps I outlined above tomorrow.

[ericnost]

Haven't looked closely yet, but see this: https://twitter.com/jywarren/status/1279856631271100416

[lightandluck]

Thanks @ericnost! That's extremely helpful!

[lightandluck]

Closing and tracking progress here: #243