Discussion about renaming branches in Homebrew

[Rylan12]

Overview

GitHub has recently added support for renaming branches. This is part of a project by GitHub to rename the default branch from master. See the github/renaming repo for more information about this process.

Git is making changes as well in the same direction. See this statement from the Git project about the change.

It's important to note that even though GitHub added the ability for users to rename branches, git still does not support this.

The Big Questions

There are three main concerns that I think we, as an organization, need to discuss.

1. Should Homebrew organization repository branches be renamed?
2. If we choose to rename our branches, what needs to be done to ensure that users aren't negatively affected?
3. What changes do we need to make to support other repositories being renamed, regardless of what we decide for the Homebrew organization?

1. Should Homebrew organization repository branches be renamed?

This is a relatively simple question. Do we feel that using an alternative name for our branches is a change that we should make?

To quote from a statement made on the SFC website called Regarding Git and Branch Naming

Both Conservancy and the Git project are aware that the initial branch name, ‘master’, is offensive to some people and we empathize with those hurt by the use of that term.

From the Homebrew Code of Conduct

The Homebrew community welcomes and encourages participation by everyone. Our community is based on mutual respect, tolerance, and encouragement, and we are working to help each other live up to these principles. We want our community to be more diverse: whoever you are, and whatever your background, we welcome you.

I think it's worth pointing out that we have actively decided to move away from certain terms in favor of "allowlists" and "blocklists" for similar reasons.

2. If we choose to rename our branches, what needs to be done to ensure that users aren't negatively affected?

This is a more challenging question. Essentially, how can we ensure that users are able to continue using Homebrew without any hiccups?

Some important things that need to be looked at before we start making any changes:

• brew update will need to handle branch name changes
• The Homebrew installer may need to be updated
• Developer commands will need to be updated
  • This includes things like bump-formula-pr, pr-publish, dispatch-build-bottle, etc.
  • This also includes Linux dev tools like the script to merge homebrew/core into linuxbrew/core
• Homebrew and third-part CI systems may be affected
• We need to ensure that none of the other services we use (e.g. Homebrew Docker containers, Bintray, Slack integrations, etc.) will be affected
• We will need to anticipate that changing the branch name may cause breakage among users who (for whatever reason) don't use brew update
• Links may need to point to the new branch name

3. What changes do we need to make to support other repositories being renamed, regardless of what we decide for the Homebrew organization?

Regardless of what we chose to do, GitHub has now given users the ability to change branches. We must try to anticipate whether or not this will cause any issues and, if it will, whether or not we need to do any work to prevent those issues from arising.

Specifically, I'm thinking of things like the following:

• brew update will fail to update taps that have had their upstream branch name changed
• Formulae may no longer work if their upstream branch name changed
  • The url may no longer be valid
  • Resources may no longer be available
  • livecheck may fail
• There may be defaults that we should change
  • brew tap-new creates a new git repository. This has already been updated to use main by default
  • There are some fallbacks that exist in brew update and other commands. These may need to be changed to not fallback on master

What Has Been Done So Far?

The good news is that some work has been already been done. I will try to keep this a running log of the tasks that have been completed.

• update can now detect the upstream branch name (#7758)
  • Note: brew update is still broken in its current state on branch renames
• update-reset resets taps to their correct upstream HEAD branch (#7769)

What Needs To Be Done

For now, the main thing that needs to be done is to come to a consensus as to what our plan will be.

I recommend that once we have answered some of these questions, an official outline of the process be drawn up (GitHub issue is fine). As this may be a longer-term process (i.e. one PR isn't going to close this issue), it will be beneficial to have a roadmap for us and for the community to reference.

[Rylan12]

1. Should Homebrew organization repository branches be renamed?

Yes. I believe that this is something we should strive to do. However, our priority should be for Homebrew to continue to work seamlessly. We should not make the change until we are ready and absolutely certain that the effects of the change will be minimal.

I think main is a good name. I'd be open to other options, too.

2. If we choose to rename our branches, what needs to be done to ensure that users aren't negatively affected?

• brew update will need to handle branch name changes

This is probably the trickiest one. If we can get brew update to Just Work when handling branch renamed, I think that everything else will become much easier.

I think this will mainly be an issue for the taps. Most users are on the stable branch of the brew repository which will not change.

I've opened #10423 where more discussions about the details can occur.

• The Homebrew installer may need to be updated

This should be a simple change.

• Homebrew and third-part CI systems may be affected

Internally, this shouldn't be too difficult. We will need to check the Homebrew/actions repository to make sure everything is compatible. There may be a few minor issues, but these shouldn't affect most users as it's an internal change.

Additionally, I know that there are some references to master in our developer commands. These would need to be updated.

The more tricky issue is whether or not we need to assume that there are other systems out there that use Homebrew that could break. I've added my thoughts on this below.

• We need to ensure that none of the other services we use (e.g. Homebrew Docker containers, Bintray, Slack integrations, etc.) will be affected

I don't believe Bintray will need any changes. I don't know anything about our Docker situation to be able to weigh in. Slack integrations may need to be updated (I'm not really sure) but this is minor. These are just the things I thought of but there may very well be more.

• We will need to anticipate that changing the branch name may cause breakage among users who (for whatever reason) don't use brew update

As much as I would like to say that breaking things for people who choose not to use brew update shouldn't be a major concern of ours, I think it needs to be. I think it's inevitable that making a change like this without considering the effects on these users will cause many complaints and unhappy users. If we can do a little extra work to try to mitigate this, we should.

My tentative idea is to essentially use a deprecate/disable/remove cycle for this as well.

• In the deprecate phase, we can have both a master branch and a new branch
  • Running any brew command while on the master branch will show a deprecation warning prompting the user to switch to the new branch. It should also note that simply running brew update will solve this.
  • We would likely use a GitHub action to keep the non-default branch in sync with the default branch
  • I think it would make the most sense to only show this message for rename issues in official taps.
• In the disable phase, brew commands will fail if the branches have not been updated. They will still have the instructions telling users how to fix the issue (run brew update or manually change the branch name)
• Finally, the master branch can be removed and the errors can no longer show.

This cycle should coincide with the typical major/minor releases.

• Links may need to point to the new branch name

The good news is this has already been done for the most part. This step will likely consist of searching through our codebase for references to master and replacing them with the replacement name or HEAD.

3. What changes do we need to make to support other repositories being renamed, regardless of what we decide for the Homebrew organization?

The biggest thing is to have brew update work. If we decide to not change the branch names in the Homebrew organization, another option would be to not support branch renames. Note that brew update-reset will

There are a few ways I can see this working:

• brew update will change branch names and handle everything (preferred)
• brew update will notice the branch name change and prompt the user to run e.g. brew update-reset (maybe we make a less-destructive command that will reset the branches)
  • Maybe brew tap --repair will help out here?
  • It would be great if we could have this be done automatically
• We do nothing and rely on tap maintainers informing their users of the change and how to proceed

I'm not that worried about formula breakage. I don't think we'll see super widespread breakage and we can handle issues on a case-by-case basis. They will most likely be a matter of changing a URL and (maybe) rebottling.

---

I think the biggest things to do are

1. Make a decision about whether or not to change branch names
2. Modify brew update
3. Communicate well
   • If we make changes, I think blog posts explaining our choices are key. Also, they will allow us to relay instructions on how to proceed for users

[iMichka]

I am in favour of the change.

Just a heads up that you forgot that linuxbrew-core needs to be migrated at the same time, and the merge script from homebrew-core to linuxbrew-core needs to be working with the new branch name. Or you can wait that linuxbrew-core is gone, but that might take another 6 months.

[Rylan12]

Thanks, I did forget about that. I'll add it to the list above.

Or you can wait that linuxbrew-core is gone, but that might take another 6 months.

This might not be a bad idea, actually. I'm not sure. Here's one more thing that I realized I forgot to mention:

It's possible that git will add new functionality in the future that will make changing branch names easier. It might be a good idea to wait until those are in place to make any changes. I don't know exactly what those will be, though.

Of course, one thing to keep in mind is that new git features won't be available by default. We may want to require using brewed git in these cases.

[carlocab]

Just leaving this link here as it's potentially relevant to the discussion: https://mail.gnome.org/archives/desktop-devel-list/2019-May/msg00066.html

It also looks like we have a tap that's been bitten by branch-renaming not fully supported as of yet: https://github.com/homebrew-ffmpeg/homebrew-ffmpeg/issues/74

Related discussion in https://github.com/Homebrew/brew/issues/10766.

[Rylan12]

brew tap --repair should fix that, and brew update should detect the rename and instruct a user to run brew tap --repair.

At least, that's what #10423 was supposed to add.

[MikeMcQuaid]

Closing but discussion can continue in here!