DISCUSS Rename master to main?

[MarcoGorelli]

The default for new repositories is now "main", so renaming might make contributing less confusing to newcomers.

scikit-learn have made this move (see issue and PR), and from https://github.com/github/renaming it doesn't look too disruptive:

Renaming a branch will:

• Re-target any open pull requests
• Update any draft releases based on the branch
• Move any branch protection rules that explicitly reference the old name
• Update the branch used to build GitHub Pages, if applicable
• Show a notice to repository contributors, maintainers, and admins on the repository homepage with instructions to update local copies of the repository
• Show a notice to contributors who git push to the old branch
• Redirect web requests for the old branch name to the new branch name
• Return a "Moved Permanently" response in API requests for the old branch name

From the penultimate bullet point above, it seems that existing links in the docs wouldn't break even if we didn't update them, but I think the

  push:
    branches: [master]

part of the CI workflows would still need renaming.

---

For contributors

The GitHub interface will typically explain what you need to do as contributor to a project that changed the default name, but putting it here as well (copying the instructions from dask dask/dask#7199).

What you'll see

Once the name on github is changed, when you try to git pull you'll get

Your configuration specifies to merge with the ref 'refs/heads/master'
from the remote, but no such ref was fetched.

What you need to do

First: head to your fork and rename the default branch there. When visiting https://github.com/<USERNAME>/pandas, you will see a notice like this:

where you can click this link (https://github.com/<USERNAME>/pandas/settings/branches), and then rename "master" to "main"

Then, locally run:

git checkout master
git branch -m master main
git fetch origin
git branch -u origin/main main
git remote set-head origin -a

[jorisvandenbossche]

I am +1 on renaming

[lucasrodes]

+1

[jarrodmillman]

NumPy, scikit-image, and NetworkX have also switched to using main as the default branch name. The switched caused a few old PRs to be closed (since the original branch had been deleted already) for NumPy:

• MAINT: Closed PRs due to branch rename numpy/numpy#18543

We also had three old PRs closed on NetworkX for the same reason (the PR contributor had already deleted their old branch). Also, I think the change caused Azure to rerun a bunch of checks, but the other CI systems didn't have any issues with the change.

Other than that (and that wasn't a big deal) everything went smoothly and it was very easy to do.

[jorisvandenbossche]

Thanks for that context @jarrodmillman !

[jorisvandenbossche]

@MarcoGorelli would you be interested to follow-up on this topic? (although the actual renaming might need to be done by an owner of the repo, I see the setting to rename the master branch)

Apart from the actual renaming and fixes in CI, we will probably need a small set of guidelines on how you can update your local development environment we can post here and on the mailing list (which we can probably adapt from scikit-learn or numpy or so).

[jarrodmillman]

Any progress on this? SciPy has changed their default branch to main now as well.

I am happy to help. For example, I could make a PR to update your repo once the GH button to rename the default branch is pushed. I could also draft an email to send to your developer list.

[MarcoGorelli]

@MarcoGorelli would you be interested to follow-up on this topic? (although the actual renaming might need to be done by an owner of the repo, I see the setting to rename the master branch)

Sorry, forgot to get back to you on this - and yes, I think the actual renaming needs to be done by the owner

[TomAugspurger]

+1 to making this change now.

[jorisvandenbossche]

+1 to do this now as well

I can do the actual rename if a PR is ready to update the repo.
In addition, we might also have to manually update the codecov settings. For the rest I don't know if any other integration needs to be updated (eg we don't have readthedocs that would have to be updated)

cc @pandas-dev/pandas-core @pandas-dev/pandas-triage

[jorisvandenbossche]

(I also updated the top post with some instructions for contributors to do, after the rename)

[jreback]

yeah ok here too

…

On Jan 12, 2022, at 7:37 AM, Joris Van den Bossche ***@***.***> wrote:  (I also updated the top post with some instructions for contributors to do, after the rename) — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you are on a team that was mentioned.

[bashtage]

I think it is a good idea. Syncing with the rest of the ecosystem keeps the mental load lower.

[Dr-Irv]

You'll have to document what people need to change in terms of their local setups. For example, I have a local copy of master and origin/master in my own GitHub remote repo. So having instructions on how to rename one's existing local and remote repos would be useful.

[jorisvandenbossche]

@Dr-Irv I included some instructions in the top post, can you check if this is clear for you? (in addition, the github UI will also provide some helper pop-up if you visit the github page after the rename)

[jorisvandenbossche]

OK, I think we have enough approvals here, so I just clicked the rename button.

So then we can actually test in practice if the instructions for contributors above are correct / clear enough, and update them if needed.

[Dr-Irv]

@Dr-Irv I included some instructions in the top post, can you check if this is clear for you? (in addition, the github UI will also provide some helper pop-up if you visit the github page after the rename)

@jorisvandenbossche Note - if you visit the instructions on the main pandas repo that pop up, those don't work. You have to go to your personal repo to follow those instructions instead.

Yes, I tried the ones you put above (although we need to publish them somewhere else??). It might be worthwhile to have people verify they have done things correctly by typing git show-ref --heads main to see that the reference was changed and typing git show-ref --heads master to show that the old reference was deleted.

Also, is there a PR that updates the docs? The docs here: https://pandas.pydata.org/pandas-docs/stable/development/contributing.html should be updated ASAP (and published ASAP) so that new contributors don't get confused about how to get started and work with git. There are other places in the docs where we refer to master and those should be changed to main.

[jorisvandenbossche]

Note - if you visit the instructions on the main pandas repo that pop up, those don't work. You have to go to your personal repo to follow those instructions instead.

Clarified that a bit.

It might be worthwhile to have people verify they have done things correctly by typing git show-ref --heads main to see that the reference was changed

I ran that locally (after already done the rename), and get:

$ git show-ref --heads main
63e7ef15b3008aa006b563cd2f5ea70cdb0e3ec2 refs/heads/main
$ git show-ref --heads master
<nothing>

How do I know this is actually correct? (I don't know what to expect from those commands, so I also don't know if this actually verified that I did the rename correctly)

although we need to publish them somewhere else

I already pinned the issue, and we can also send a notice with the instructions to the mailing list (other places to publish?). But let's first make sure the instructions are fully clear and complete.

[Dr-Irv]

How do I know this is actually correct? (I don't know what to expect from those commands, so I also don't know if this actually verified that I did the rename correctly)

As best as I can tell, if you get a result that shows refs/heads/main and no result with refs/heads/master, then things were done correctly.

[lithomas1]

@jorisvandenbossche Can you update the wheel building repo too(MacPython/pandas-wheels)? I'm pretty sure you're breaking the nightly builds. Things that should be updated would be e.g. here
https://github.com/MacPython/pandas-wheels/blob/6085fe47d7b262c93f17cb5e36ed41d1738d74d7/azure/windows.yml#L14
(among other places)

[jreback]

merged via #45336 (ex comments here: #39577 (comment))

[Dr-Irv]

@jreback I know we closed this because of the PR that updated the docs, but is there a way we can push the doc update to the web site now so that any new contributors have the right docs available?

[simonjayhawkins]

We link to the docs for the latest released version, so currently 1.3.5. The update has been backported to 1.4 so will be published end of next week and stable link updated.

[jorisvandenbossche]

Can you update the wheel building repo too(MacPython/pandas-wheels)

Done: MacPython/pandas-wheels#172

In addition, we might also have to manually update the codecov settings

This might already be done by changing https://github.com/pandas-dev/pandas/blob/main/codecov.yml, but in any case I also updated the settings in the codecov web page

[jorisvandenbossche]

For the docs: the dev docs are already up to date: https://pandas.pydata.org/docs/dev/development/contributing.html (but indeed the "released" docs will be behind for some time)

[Dr-Irv]

For the docs: the dev docs are already up to date: https://pandas.pydata.org/docs/dev/development/contributing.html (but indeed the "released" docs will be behind for some time)

Is there a way to push the backported 1.3.5 changed docs to the web site as the "released" docs as an exception to the regular process?

[simonjayhawkins]

Is there a way to push the backported 1.3.5 changed docs to the web site as the "released" docs as an exception to the regular process?

developers should be using the docs on the dev branch. https://pandas.pydata.org/pandas-docs/dev/

All links to contributing to pandas should link to the dev version of the docs. Please report any cases where this is not the case.

[simonjayhawkins]

git remote set-head origin -a

I might be an exception to the norm, but my default branch on my fork is not main so that I can add github action workflows (such as bisecting regressions)

so the instrcutions could be ?

git remote set-head origin main

[Dr-Irv]

All links to contributing to pandas should link to the dev version of the docs. Please report any cases where this is not the case.

If you go to https://pandas.pydata.org/docs/ and at the top click Development, it goes to https://pandas.pydata.org/docs/development/index.html . Also on that same top level page, there is a link at the bottom that says "To the development guide" that goes to the same place.

For me, those are the obvious places to look to get started with development with pandas.

[simonjayhawkins]

For me, those are the obvious places to look to get started with development with pandas.

could consider changing those links.

[simonjayhawkins]

could consider changing those links.

#45370 is a better solution

[Dr-Irv]

could consider changing those links.

#45370 is a better solution

It helps, but if the default value there is the current release, it's still not obvious that things change in between releases, so maybe we should also update https://pandas.pydata.org/docs/development/index.html#development to tell people to look at the most recent in-development version to know the latest and greatest development info.

[simonjayhawkins]

so maybe we should also update https://pandas.pydata.org/docs/development/index.html#development to tell people to look at the most recent in-development version to know the latest and greatest development info.

moving to 1.4.1 for the docs update.

[jorisvandenbossche]

Some projects have a note at the top of a page when looking at older versions docs to refer to the stable docs instead (see eg https://numpy.org/doc/1.19/ or https://mne.tools/0.23/index.html. The code in mne to do this is some javascript and is located at https://github.com/mne-tools/mne-tools.github.io/blob/main/versionwarning.js).
We could maybe do something similar but specifically for the contributing docs, and only in that section of the docs add a warning if you are not looking at the dev docs?

[jreback]

this is all done.