Did-core: rename master branch

[brentzundel]

Summary

We should rename the branch master to main and use that going forward for our work.

From Problematic Terminology in Open-Source on master/slave terminology in software:

Use of this term is problematic. It references slavery to convey meaning about the relationship between two entities.

Removing this terminology from our workflow is a small gesture to include more people from marginalized groups in this project.

(I’m open to names other than main)

Technical Steps

• [x] create main branch from master
• [x] make main the default GitHub branch
• [x] modify github/central to use main for release notes reloading
• [x] redirect PRs to main in w3c/did-core
• [x] move branch protections from master to main
• [x] modify docs to reference main instead of master
• [x] delete master branch to avoid confusion?

Feedback?

[iherman]

We should wait with this. At the moment it seems that the github.io pages do _not_ work with any other branch name than master. AFAIK, github is aware of this issue, and they want to make the relevant setting more flexible, but we should wait until this is resolved.

[selfissued]

Please no. This wouldn't just affect the primary repository. This would affect every branch, every fork, and every local clone, requiring manual steps by all participants to make parallel changes to these copies. The chances of everyone getting this right are close to zero.

Using git correctly is already complicated enough. Please don't make this repository even more complicated than usual.

[peacekeeper]

We should try to find ways to make this change as painless as possible (e.g. by waiting for Github to support this better as suggested above). But in general I am in favor of this change across all our repos. Since DID technology has its roots in an ideology related to individual freedom and sovereignty, this "small gesture" should be even more important for us than for others.

[yancyribbens]

trunk would also be a good choice instead of master.

[brentzundel]

I believe the primary thing we are waiting for is github.io pages to work with a branch other than master
Hopefully there will be additional tooling from github that will make this transition straightforward.

[brentzundel]

still waiting on support in github.io pages for a branch other than master

[brentzundel]

It looks like they're still working on tooling to make this easier: https://github.com/github/renaming#later-this-year-seamless-move-for-existing-repositories-
but these should be in place by the end of the year.

[msporny]

still waiting on support in github.io pages for a branch other than master

This is supported now, so change should be easy as long as W3C tooling doesn't assume master branch, which if it does, it should be fixed.

[brentzundel]

If I understand correctly, it is the possibility of breaking some of the W3C tooling that has fueled much of the pushback on this.
@iherman does the W3C tooling assume the existence of a master branch and can that be changed?

[iherman]

I do not think the issue is whether the tooling relies on the name "master"; it probably does not. The issue is whether it is prepared for a change of a repository that has already entered the system, so to say.

I add @deniak here, maybe he knows, and he also knows whether other repos have already gone through such a change.

[deniak]

I do not think the issue is whether the tooling relies on the name "master"; it probably does not. The issue is whether it is prepared for a change of a repository that has already entered the system, so to say.

I add @deniak here, maybe he knows, and he also knows whether other repos have already gone through such a change.

I'm not aware of any specification repositories that have renamed the branch. @plehegar is actually coordinating the switch. He should have more details.

[msporny]

Github: "On October 1, 2020: newly-created repositories will default to main"

https://github.com/github/renaming

Github pages already supports publishing from branches other than master.

I will run a test to see how easy it is to use a non-master branch from now on.

[iherman]

Yes, and I already use this in a Working Group that we have just started. My worry is the past (past references, previews, etc) as well as to secure that ECHIDNA would work properly...

[msporny]

My worry is the past (past references, previews, etc) as well as to secure that ECHIDNA would work properly...

Only way to find out is to do it -- W3C staff is going to be dealing with this for many of its existing groups given that Github is going to allow a mass-rename feature by end of year.

I'm willing to put in the work to get this issue closed by working closely with @deniak and others if there are issues.

[deniak]

There shouldn't be any problem for Echidna as long as the travis configuration has the right branch. However, I'm checking with @plehegar to see if other tools may be affected by the switch.

[msporny]

In the meantime, Github has moved ahead and made this easy. I'll make the change before CR... this has been hanging out here for long enough.

[msporny]

I have created a 'main' branch, but do not have repo update permissions. I have also updated all publication variables to refer to this new branch: 46532b9572dc746c46ec73b06953aba9c15ec512

@iherman, please give me the appropriate repo permissions to do the rest of the changes, or set main as the default branch (and default publication branch for docs).

This issue will be closed as soon as the repo settings are updated.

[iherman]

I have created a 'main' branch, but do not have repo update permissions. I have also updated all publication variables to refer to this new branch: 46532b9

@iherman, please give me the appropriate repo permissions to do the rest of the changes, or set main as the default branch (and default publication branch for docs).

@brentzundel I'd need your nod to proceed.

[iherman]

B.t.w., @msporny, what will happen with the PR-s out there? Is it possible to change the 'target' branch of a PR to 'main', or is it something happening automatically by virtue of 'main' becoming the default branch?

If we do that, we should also do it with the other repositories.

[msporny]

B.t.w., @msporny, what will happen with the PR-s out there? Is it possible to change the 'target' branch of a PR to 'main', or is it something happening automatically by virtue of 'main' becoming the default branch?

The existing PRs will have to change to use main; it's an easy task... you go to the PR, click edit, and then click main as the target branch. I chose to do this now because we only had 3 outstanding PRs (I had held off for months because of the number of outstanding PRs).

Once main becomes the default branch, all future PRs will target main automatically.

If we do that, we should also do it with the other repositories.

Yes, agreed, but making this repo the first one so we can learn from any unforeseen complications... at present, it seems like everything is there for us to make the transition.

[iherman]

The existing PRs will have to change to use main; it's an easy task... you go to the PR, click edit, and then click main as the target branch.

Github (and git) has an infinite amount of tricks... :-)

As soon as @brentzundel gives his thumbs up I will do this.

[iherman]

Just making a note here:

Branch protection policies need to be transferred to the new branch

this is an extra admin step that I will have to do if we make the changes...

[selfissued]

The consequences of changing the name of the master branch are much bigger than just active PRs. To do this without disrupting people's ability to work, we also need to publish simple, clear instructions on what to do to existing forks (such as https://github.com/selfissued/did-core) and to existing clones (such as the one I have at C:\Users\mbj\Documents\GitHub\w3c\did-core on my primary work laptop).

Please let's not change some things until we can tell spec developers how to make all the necessary compensating changes.

[iherman]

https://github.com/github/renaming#later-this-year suggests that some of the extra chores will be automatized by GitHub. We may want to wait for that to make the change; that may also take care of the problems referred to by @selfissued

[msporny]

We may want to wait for that to make the change

-1 on waiting -- we've been waiting since this issue was opened six months ago. The changes are easy for the Editors and easy for people w/ existing clones. This is not difficult, let's just do it.

Please let's not change some things until we can tell spec developers how to make all the necessary compensating changes.

The only changes needed right now have been signalled to the current open PRs. People with active forks need only either 1) git pull and git checkout main, OR 2) change their upstream -- both of those are easy to do and I can help anyone having an issue with it.

Let's move forward with this -- it's taking more time to discuss it than to just go ahead and do it.

[brentzundel]

@iherman +1 from me.
Special thanks to @msporny for getting this done.

[selfissued]

@msporny - I'm sorry but you're assuming expertise in git that many people simply don't have. You're using terms like "change their upstream" without saying how to do it or what the implications of doing so are. I suspect most contributors have never done this, and so their chances of getting it right are small. For instance, is that something I'd do at https://github.com/selfissued/did-core or at C:\Users\mbj\Documents\GitHub\w3c\did-core or both? And how?

Is this something I do to all my existing branches or only to the master branch?

I suspect I'm not the only one who doesn't know exactly what you're talking about doing. But I am willing to say so.

Please let's not do any of this until the issue contains exact instructions on what contributors need to do when and where so that their ability to contribute is not disrupted. Thank you.

[msporny]

@selfissued wrote:

Please let's not do any of this until the issue contains exact instructions on what contributors need to do when and where so that their ability to contribute is not disrupted.

Instructions for people working with the did-core repository follows, once the default branch is set to main (which will happen once this issue is closed):

If you don't have any active pull requests for did-core and clone the did-core repository (this repository) directly:

1. Delete your current repository.
2. Do a fresh git clone of the did-core repository. Instructions are here: https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/cloning-a-repository

If you don't have any active pull requests for did-core and work from a personal fork:

1. Delete your personal fork of the repository.
2. Do a fresh fork of the did-core repository. Instructions are here: https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo

If you are working on a pull request for did-core:

1. Request a pull request as you would normally do, but set the target branch to main when opening the PR. Instructions are here: https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/changing-the-base-branch-of-a-pull-request

If you already have an active pull request for did-core, there are instructions on what you should do in your PR. If there aren't, use these instructions: https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/changing-the-base-branch-of-a-pull-request

@selfissued, that is every variation I can think of people hitting. If anyone has issues with the switch over, I will help them make the transition.

[iherman]

@msporny @brentzundel

I have flipped the default branch to 'main'.

• Interestingly, the PR 'targets' have been changed automatically to target the 'main' branch (unless one of you guys have done that; if so, exactly how?)
• I have made a manual copy of the branch protection rules, ie, the same restrictions/authorizations should be valid for 'main' as it used to be for 'master'
• I have changed the github.io setting to draw from the 'main' branch rather than the 'master' branch.
• I see that the .travis.yml file has already been changed
• on the description above: I wonder whether there is a real need to remove and re-clone the personal copy of the repository. I have just checked out 'main' and then removed (locally) the 'master' branch; I do not think there is anything else to be done a local clone, is there? (I use git from within Visual Studio Code and from the SourceTree or GitKraken desktop apps). After all, the 'default' branch is a GitHub notion as opposed to a generic git notion.

Please check if everything is fine or whether we have forgotten anything. Once the dust settles, we should do the same changes on our other repositories.

[msporny]

I wonder whether there is a real need to remove and re-clone the personal copy of the repository.

There isn't, but then it would require people to delete their local master branch or remember to not use it... upstreams might still point to master, so people would get confused. I tried to give instructions that wouldn't lead to corner cases. :) -- for people that know how to use Git to work with branches and upstreams, none of this should be an issue... they'll know what to do.

[iherman]

@msporny or @brentzundel I believe a mail to the WG about this would be in order. I guess this issue can be closed

[msporny]

@iherman I've checked as much as I can... everything seems to be working. I have a backup of the master branch on my machine, so if something goes terribly wrong (at this point, I really, really doubt something bad will happen), we can always roll it back.

Please delete the master branch (it still has branch protection rules on it, so I can't do it). At that point, we'll really know if all the changes have been applied correctly (I expect that they have been).

[iherman]

Master branch deleted. R.I.P. :-)

[brentzundel]

Thank you @msporny and @iherman for getting this done. The fallback so far, even on the active PRs I've got in process, has been minimal. I'm also more than happy to help folks for whom this causes issues.

I also agree this is ready to close.