Rename master branch to main

[schneiderl]

According to our Inclusive Language section on the Contributing Guide, we should always try to use inclusive language.
According to the Guide,

"primary"/"secondary" instead of "master"/"slave"

I believe that if that is in our Contributing Guide, we should follow it in our main repositories at least. That includes how we name our branches.
Our "main" branches are still named "master" in all the repositories from the organization.

Should we think of renaming this?

Also, if we do rename, I would suggest "main" instead of "primary" following what is being done by GitHub.

[sbrl]

Great point. Yeah, I think main is fast becoming the new standard. Is there any word on whether Git itself will be changing its default too, and if so in what version?

@owenvoke, will this result in an impact on any of our GitHub actions or automation?

@agnivade: would this have an impact on the tldr-bot at all?

[schneiderl]

The only thing I could find on Git is that they are really cautious about renamings of the sort.

See: this under Changing the master branch name section.

Either way, this section only shows how one should proceed while changing this. I could not find anything about making "main" standard.

[bl-ue]

@sbrl @schneiderl See the Git project's official statement and code change. I found that at GH's Blog Post -> Repo.

[agnivade]

Don't think so it's going to cause issues with tldr-bot.

[owenvoke]

So, the only required changes for GitHub Actions would be a couple of references to master in the if blocks. We do however reference master in quite a few other places.

I've created a branch to show the differences that would be required: master...owenvoke:feature/main

One thing to note, I think when changing the default branch, we'd have to go through all PRs and make sure that they are pointing at the new one. However, I don't think that should be a problem.

---

On another note, I'm wondering if we should do this for our other repositories? 🤔 The tldr-bot and tldr-lint repos would probably be the easiest. I think the master branch should in theory be automatically redirected, so

[bl-ue]

I think only org owners change the default branch.

@owenvoke / @sbrl / @agnivade will you please change the default branch on the following repos to main?:

• .github
• tldr-bot
• tldr-c-client
• tldr-lint
• tldr-node-client

I'll open draft PRs to rename any branch names to main on those repos now.

[owenvoke]

@bl-ue, are we sure that there are no issues with this? If so, I'll open my PR in this repository.

[sbrl]

I've changed .github as I don't think that one will cause any issues, but it showed a message to notify me that this won't (of course) rename local working copies of repositories, which could be a particular problem for some of our repos.

[owenvoke]

I've renamed the branch in tldr-lint as I don't think this affects anything either.

[sbrl]

I think the tldr-node-client, tldr-c-client, tldr-python-client, and of course the main tldr repo could pose some considerable issues.

For the former 3, developers probably have it checked out with the master branch, so it might be wise to open separate issues there and potentially set a date in the future the change will occur (and also check the GitHub actions).

For the latter, it is of course our main repository, with probably thousands of clones all over the place. We also may have a non-zero number of clients who are hard-coded to checking out the master branch too.

[bl-ue]

So what would we do for the clients? Set a date several months in the future, notify all the clients and request that they update to use main, and then change the repo, and then just deal with the potential load of issues opened by users needing to update their clients?

[MasterOdin]

Please set main as the default branch for tldr-python-client. As I'm the only maintainer on it at the moment, and it's got only one PR open, the impact is minimal.

[owenvoke]

@MasterOdin, I'm happy to change this. However, I can't rename it as main already exists, so it won't show the prompt to anyone who visits the repository. If you don't mind it not having the notice (or redirect, afaik), then I'll update it to main manually. 👍🏻

[bl-ue]

I think the redirect is important. @owenvoke main already exists because @MasterOdin is testing with it. Don't rename it yet—wait untill he's done so that the redirect is there.

[MasterOdin]

@owenvoke I failed to realize that GitHub was offering a rename / redirect service on their settings page. I've gotten rid of the main branch, and feel free to rename master to main now.

[owenvoke]

@MasterOdin done! 👍🏻

[sbrl]

Related reading: https://github.com/github/renaming

[MasterOdin]

In my opinion, the best option for the main repos (tldr-pages/tldr and tldr-pages/tldr.github.io) would be to set a date in the future (e.g. 03/01/21) where main is the new default branch, but keep master around for a couple of years to allow ecosystems to move on (e.g. ubuntu/debian packages, individual clients) and then have a GH action that runs on pushes to main that then fast-forward merges that commit to master. This gives a best of both worlds as it were without much downsides beyond just "we still have a master branch", but that's just a necessary evil at this point to not break the wider usage.

Note: Given GH's new rename system for branches, renaming the default branch will automatically update PRs so it should be fairly painless for in-progress PRs from external collaborators.

[sbrl]

Sounds like a plan, @MasterOdin! The 3rd January 2021 has already passed though, so I'd suggest something like 1st April 2021 or something.

[bl-ue]

@sbrl I think he means March 1st, maybe we're getting American vs. European date formats mixed up?

[MasterOdin]

Yup, I meant March 1st, 2021.

[sbrl]

Oh, I see. Yeah, we could do that. It doesn't give too much time to update the GitHub actions automation etc, so I'd suggest we have a PR ready to merge at the time before committing to a date.

[MasterOdin]

Perhaps a better notion would be to make a PR to set it up so that pushes to master get mirrored to main, and then let that go for a month or so to work any kinks out and then reverse it once main gets promoted to default.

[sbrl]

That's a cool idea too, @MasterOdin! @owenvoke, is that feasible with GitHub Actions at all?

[MasterOdin]

Yes, it should be, and should be as simple as doing:

  
name: CI

on:
  push:
    branches: [ master ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
      - name: Commit report
        run: |
          git config --global user.name 'TLDR Bot'
          git config --global user.email 'tldr@users.noreply.github.com'
          git checkout main
          git merge --ff master
          git push

given that it's a --ff merge, might be able to drop the git config lines, but not totally sure. From there, could add a PAT with repo scope to use here to trigger other actions if so desired, but that's the gist of it anyway.

[owenvoke]

We could always use this action as well. 🤷🏻 https://github.com/marketplace/actions/mirror-branch

[sbrl]

We could even start the ball rolling here by creating the new main branch and mirroring from master to main to start with, and then flip them over at the specified date?

[MasterOdin]

Agreed. I think we could do that now, with the proposed GH action going to pick up any intermediately made commits before the workflow gets added.

[bl-ue]

Would we be changing the default branch to main? Unless we're doing that, I don't really see the point of @sbrl's suggestion.

[bl-ue]

I don't really see why we can't switch the default branch to main right now, so long as we're mirroring to master on every push.

[MasterOdin]

I think it's a "let's make sure this works as we expect" deal so that we don't just switch over and potentially break a bunch of clients.

[sbrl]

Yeah. The idea is that we first start with main as an extra branch that mirrors master, so that clients who pull direct for the GH repo can have a chance to test things out.

Then, we can flip it over to have main as the default branch and master as the mirror.

Finally, we delete the master branch altogether after some time.

Though all existing PRs would have to be reopened when we flip from one to the other....

[bl-ue]

Though all existing PRs would have to be reopened when we flip from one to the other....

What do you mean by that? Do you mean 'existing, open PRs'?

[owenvoke]

@sbrl, when changing branch through the UI it automatically changes the PR base branch. 👍🏻 Or at least it does when you specify a branch rename.

[bl-ue]

The mirroring is working well. It takes ~20 seconds for commits pushed to master to be mirror-pushed to main. The next thing to do would be to switch them over. That shouldn't cause problems for clients because the two branches are almost always indentical. When should we set the date? April 1st?

[MasterOdin]

Need to also set-up a similar thing for https://github.com/tldr-pages/tldr-pages.github.io for people grabbing the zip through the githubrawcontent link. Will do that tomorrow.

[bl-ue]

@MasterOdin did you ever get back to this?

[MasterOdin]

Done: tldr-pages/tldr-pages.github.io#58

[bl-ue]

It's been some time now. Obviously, switching over won't cause any harm. We've waited a while; the tldr and tldr-pages.github.io master → main mirroring has been working every time, about 20s or less the commits are mirrored over.

Why not just change it now? @sbrl @owenvoke

[owenvoke]

@bl-ue, I've opened #5707 which should cover anything that needs changing.

[sbrl]

In terms of setting a date for the flip over, @owenvoke suggests the 1st of May:

I propose May 1st, it's a Saturday so we (probably) would have less contributions and usage of the clients. And it's the first of the month, so a memorable date. And also, it's relatively soon.

Source: https://gitter.im/tldr-pages/tldr?at=607c280bb6a4714a29d0bd95

This sounds good to me too.

Steps that need to be performed:

1. Delete the existing main branch
2. Rename master → main
3. Switch branch protection rules master → main
4. Merge feat: update to use main branch as default #5707

[sbrl]

[sbrl]

The rename for master → main is complete.

Please watch out for new PRs that merge against master, as I have been unable to create a branch protection rule on master that doesn't also block GitHub Actions from pushing to it.

Note that the GitHub action did not create master again automatically - I had to do this myself.

[schneiderl]

Nice! Thank you all for the effort.