0005: Change Default Git Branch to main

Summary

This proposal outlines a plan to shift the default git branch for project repositories from master to main. This is following a broad shift being done within the wider FOSS community.

Motivation

Currently, the default git branch in our repositories is generally master. This is an unfortunate name left over from git’s inspiration Bitkeeper. Bitkeeper had “master” and “slave” repositories, with the “master” repository making up the source of truth for the source code. This naming scheme is unfortunate at best, as it directly relates software development to the power dynamic, horrors, and institution of slavery. While not everybody relates the word master to slavery due to cultural and historical differences, we aim to be an inclusive community. Such wording should not have a space when it has clearly unacceptable background for various groups of people.

GitHub, GitLab, and Forgejo have switched to using main as the default branch of new repositories, along with sourcehut containing direct documentation referencing the switch. As such, it is obvious that the direction that the FOSS communities are going is towards main, and we should follow suit.

Consequences

Users should not see any outward changes, as this will only affect handling project repositories through git, which will not propagate to usage.

Contributors will have to relearn muscle memory when dealing with project repositories. Along with this, existing merge requests targeting the master branch will have to be recreated to target the main branch instead as GitLab does not have a way to change the target branch after MR creation.

Maintainers will have to ensure that new MRs are sent to the correct branch while the master branch still exists during transition and also ensure that any new code does not hard-code the master branch. Maintainers of non-critical repositories that are not stated in the implementation plan shall move their projects to main within one month after the acceptance of this MR, with GitLab admins moving the default branch if the deadline is not met.

Projects will have to be updated to ensure that they do not hard-code the master branch anywhere.

Implementation plan

  1. Identify every instance of hard-coded master in our repositories and place them in an issue under the organizational repository.

    1. This step also includes modifying wiki references to master, but that can be done asynchronously as projects are updated to use main.

  2. Create MRs to repositories that hard-code master, changing the string to main. Do not merge these yet, as they will all have to be merged at once to prevent breakages.

  3. Create an MR to pmbootstrap to add a script to migrate the pmaports work folder created by pmbootstrap from master to main.

  4. Test changing the default branch of a small repository with few open MRs from master to main. A good candidate for this is one of our repositories implementing a versioned program, such as tinydm. Using a repo with tags allows us to safely move the default branch from master to main without breaking builds.

    1. Changing from master to main will be done by branching main from master, pushing it, and setting it as default. Then, push a commit to master stating its depreciation in the README, and pointing to the main branch.

  5. Ask maintainers of all projects except bpo, pmbootstrap, pmaports, and ci-common to move the default branch to main. A script will be provided to simplify the work.

  6. Release an edge blog post stating our plans to move the default branches of essential repositories to main.

  7. For ci-common:

    1. Branch main from master.

    2. Merge MRs that change the branch to pull for ci-common from master to main.

    3. On master, edit the install_pmbootstrap.sh script to print a deprecation error and exit 1. Delete all other files except the license and the README and add a deprecation notice pointing to main to it.

  8. For pmbootstrap:

    1. Branch main from master.

    2. Merge MRs that change the branch to pull for pmbootstrap from master to main.

    3. On master, add a commit deleting all files except the license, the README, and the branch migration script. Add a deprecation notice pointing to main to the README.

    4. Release a new version.

  9. For bpo / https://mirror.postmarketos.org:

    1. Shutdown.

    2. Move master to main

    3. Symlink master to point to main.

    4. Start.

  10. Do the following at the same time:

    1. Shutdown bpo.

    2. In pmaports, bump pmbootstrap_min_version to the new pmbootstrap release.

    3. Branch main from master in pmaports.

    4. Adjust channels.cfg in pmaports.

    5. Delete all files except for the license and README in the master branch of pmaports and point to the main branch in a depreciation notice in the README.

    6. Merge MRs that fix hard-coding the master branch of pmaports.

    7. In bpo, replace “master” with “main” in the database.

    8. In bpo, adjust the config to build from main in pmaports.

    9. Adjust https://pkgs.postmarketos.org/ to point to main.

  11. Once the move is verified working, backport any patches to branch hardcoding that effect earlier supported versions of postmarketOS.

The proposer

This proposal was written by Aster Boese (@JustSoup321), with help in the implementation plan from Oliver Smith (@ollieparanoid).

Blocking issues

None not listed in the implementation plan.