Community's take on changing `master` branch to `main`

In the wake of recent events, a good part of the git-using community is converging to use main as the name for the default branch instead of master. Some related discussion:

And github seems to be changing the default branch to main:

We started talking about it in scikit-learn here, but @rth rightfully raised that this is a topic probably better raised at the Python community level.

It would be nice to see if there’s some sort of a consensus in the community and somewhat coordinate the change (if we decide to do so) with possibly a coordinated deprecation period, i.e. not deleting the master but have it as a mirror to the new branch (e.g. main) for a while.


We should do it. But as we’re a large project you are right, we need to work out how to do it without breaking forks, pending PRs, CI & bot automation, and such. It seems like there will be a lot of projects in the world doing the same which should result in some best practices.

I’d love it if Github could make it transparent such that the names master and main were synonymous and just exposed main instead of master as the only/default in new clones and forks as a way to make the transition less disruptive. Given how git works, I don’t know if that is feasible.

I consider this “desired”, but not something we should rush.


I wonder about, instead of switching from one symbolic name to another, going ahead and forking the 3.10 branch, marking it as the default, and phasing out master that way. When 3.11 time comes around, we fork that branch from 3.10 and mark it as default when ready.

I’m not sure that won’t cause havoc with some automated processes, though :slight_smile:


I suspect that might get weird after every branch cut just due to how Github works. We want PRs to be made against the main branch as they can stay around for a while before they land and our workflow is to always land in main (master today) and backport to releases. If the main branch changes in the interim, can that PR be automatically retargeted to a new branch? (this is the same issue with open PRs today against master if a main branch rename lands)

1 Like

I don’t think there’s any particular reason that we must keep that bit of the workflow; we could allow miss-islington to do forward-ports as well as backports and allow contributors to open their PR against whichever branch they want. There’s a slim chance this would also help with the annoyance where everybody gets pinged for review when someone opens a PR against a different branch than the change was developed from :slight_smile:

1 Like

Why not “trunk” instead of “main”. Doesn’t everyone still have love for the good old days of SVN :smiling_imp:


I’m not sure the word “master” really hurt people and this word policing really help people. But since I believe people living in US and English speaking world should decide what word should be banned, I abstein from voting.

My alternative ideas for new default branch name are:

  • “dev” – Since we use the default branch only in early stage.
  • “next” – Since we use the “next” term in `Misc/NEWS.d/next".

I think the “main” and “trunk” branch is good too. As one of Japanese, I familiar to “main” than “trunk”. I used subversion so I know “trunk”. But many young people don’t know VCS other than git.

Anyway, I heard Github is developing tool for this change. Let’s wait it.


I don’t mind the name change from master to main. Though, I agree with @methane on waiting to see how GitHub implements this change.

1 Like

Has GitHub said anything about how they might make this transparent (or at least easier) for their users? I’m supportive of the change, but if GitHub can work most of the magic at their end, then I think it pays to see what (if any) magic they announce.


I would prefer not to change the primary branch name away from ‘master’. Creating taboos never helps.


There is no official announcement yet.
I saw this article.

They also said they are releasing guidance and tools for users who may choose to rename their default branch in existing repositories.

If I’m not mistaken, there’s an API end point where you can update the base branch as well, and I’m sure even if this doesn’t work, the new “tools” github’s going to publish will support that.

Now assuming we have the tools needed for the switch to happen, I think there are still things which need to be talked about and decided. I’m hoping to come up with a workflow which can also be used by the rest of the community, i.e. projects other than cpython.

Setting up the hypothetical pipeline, would also give us a better idea of what tools we need. So as a starting point, maybe we could have:

  • create the new branch from the current master (for the sake of it let’s call it main for now)
  • make it the default branch on github
  • change the documentation and CI to reflect the change
  • make sure it’s documented wherever required that the master branch will be removed on a specified date
  • if build/release scripts are on different repos, the release manager(s) should make sure the change is reflected there
  • request all new PRs be made against the new branch
  • change existing PRs
    • ask maintainers to make sure they change the target branch of PRs they work on, to the main branch (link) OR
    • change the base branch of all PRs from master to main in bulk if possible
  • double check in CI or with a bot
    • have a CI step which fails if the PR targets master - this would only show up on PRs once they rebase or merge the latest master/main, so it’s not reliable for old PRs AND/OR
    • have a bot which comments on all PRs which target master
  • have a CI step on main which adds the newly merged PRs to master to keep backward compatibility as long as master stays there
    • it may be useful to make sure master stays a copy of main to prevent accidental changes directly to master by people who have write access to it

The list may seem trivial to many of you, but it isn’t to many others. It would be nice to put our efforts together and avoid reinventing the wheel(s) in each of our projects. There are a few questions which we need to think about:

  • would we go with whatever github chooses as the new name for the default branch? Or do we like any specific name. This may be better discussed once we know what the new name is gonna be
  • what’s the deprecation period for master? It’s probably worth keeping for a while to avoid breaking all the CI scripts which depend on our default branches. If we do this, then for how long?
  • Does this need a PEP?



Based on the discussion in our company, I went a bit further in my project and adopted a convention where branch name signifies it’s purpose.

Thus, I now have prd, stg and dev.


This approach makes the most sense to me. I’ve always had a develop branch for in progress work, but we plan on renaming the base branch to stable/production for our projects.

1 Like

Official GitHub guidance has appeared!