[RFC] rename 'master' branch to 'main'?

[jameslamb]

Description

Opening this to solicit feedback on the question:

Should LightGBM change its default branch from master to main?

I promised @borchero like a year ago that I would open this 😬

Impact of renaming "master" to "main"

According to https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch and https://github.com/github/renaming, GitHub will handle many things for us:

• 🆗 most URLs with /master/ in them will automatically redirect to main, and in the UI GitHub will display a note saying it changed

example: https://github.com/dask/dask/blob/master/.git-blame-ignore-revs*

• 🆗 branch protection rules will automatically be updated
• 🆗 commit hashes and tags will be unchanged
• 🆗 PRs will automatically be re-targeted

But some things will break:

• ❌ raw.githubusercontent.com links will break
  • example: https://raw.githubusercontent.com/dask/dask/refs/heads/master/.git-blame-ignore-revs
• ❌ any git pull explicitly referencing master will not work
• ❌ external-to-this-repo guides referencing the master branch may be incorrect (broken links, advice to use git commands that no longer work, etc.)
• ❌ contributors may need to update their forks and local clones

Benefits

In exchange for those impacts, LightGBM would be consistent with a large proportion of other open source projects using git, including:

• all conda-forge feedstocks: https://conda-forge.org/news/2022/02/13/default-branch-migration-from-master-to-main/
• all Dask repos: Renaming master to main dask/community#68
• all new GitHub repos by default: https://github.com/github/renaming
• pandas: DISCUSS Rename master to main? pandas-dev/pandas#39577
• networkx, numpy, scikit-image: DISCUSS Rename master to main? pandas-dev/pandas#39577 (comment)
• scikit-learn: Question: Changing the default branch (master) to main? scikit-learn/scikit-learn#17595
• scipy: DISCUSS Rename master to main? pandas-dev/pandas#39577 (comment)
• many other popular projects in the microsoft/ org
  • https://github.com/microsoft/vscode
  • https://github.com/microsoft/TypeScript
  • https://github.com/microsoft/onnxruntime

This convention of main has become so common that I think at this point it's what contributors expect when the work on a git-based project. Even git itself will now warn when you create a new repo and use master as the default branch.

$ git init
hint: Using 'master' as the name for the initial branch. This default branch name
hint: is subject to change. To configure the initial branch name to use in all
hint: of your new repositories, which will suppress this warning, call:
hint:
hint: 	git config --global init.defaultBranch <name>
hint:
hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and
hint: 'development'. The just-created branch can be renamed via this command:
hint:
hint: 	git branch -m <name>
Initialized empty Git repository in /Users/jlamb/blegh/.git

Approach

I think this would go roughly like this:

1. put up a PR changing all master references in source control (links, CI configs, etc.) to main, get that approved
2. go into the repo settings and rename the default branch to main
3. push a new commit to that PR to re-run all CI
4. merge that PR

And then manually adding a note about this to the release notes of the next release.

Timing?

Proposing we do this as soon as we have agreement on this issue, ideally before the next release (which will probably be v4.7.0).

Notes

Tagging other maintainers for comment, whenever you have time.

@guolinke @shiyu1994 @StrikerRUS @jmoralez @borchero @btrotta

[StrikerRUS]

I'm neutral to this change...

[StrikerRUS]

Just remembered that we also have to update some hooks, e.g. RTD automatic builds.