search

betterscientificsoftware / bssw.io

Better Scientific Software Homepage
https://bssw.io
Other
140 stars 90 forks source link

More inclusive branch naming on GitHub #674

Closed markcmiller86 closed 11 months ago

markcmiller86 commented 3 years ago

GitHub has replaced its default branch name of master with main. It has also implemented a number of features to help organizations, projects and individual users change branch names and change the default branch name for new repositories.

These efforts are part of a larger community push towards more inclusive practices including the language the community uses to refer to things we use in our daily activities.

Two activities are proposed...

Tasks to change 'master' to 'main' in bssw.io repo

These operations are to be performed in order in the following groups

rinkug commented 3 years ago

@markcmiller86 : Is the plan to highlight these feature changes?

pagrubel commented 3 years ago

@markcmiller86 Are you suggesting a cc to this?

markcmiller86 commented 3 years ago

Are you suggesting a cc to this?

No. I am recommending we update this github repo to use main instead of master for the main branchname. I think that will involve working with the Sandbox folks to fully move it over. But, we should do it.

markcmiller86 commented 3 years ago

So, as I have spent more time studying the inclusive language issue which is very obvious with the pair of terms master and slave in proximity to each other, I've become more on the fence regarding the term master in isolation. I am aware of many instances of the use of master that may pre-date or otherwise be wholly indpendent of the history of enlsavement or other harmful associations what may represent a substantial inclusivity barrier for someone. I have been looking for exposition on this issue if any in the public domain and haven't yet found any by thought leaders within the community.

bartlettroscoe commented 3 years ago

This is one of those issues that I am willing to do if everyone else is willing to do as well. Otherwise, it is confusing if there are a mix of repos with 'main' and 'master' having to remember which repo uses which.

bartlettroscoe commented 3 years ago

It seems like until the Git project itself puts out a first release where the default default branch name is 'main' instead of 'master', we can't be too hard on projects that don't make this switch. The article:

says that the Git project is working on making 'main' the default default branch name. But I see no evidence this has happened yet. I actually think they may need to name such a Git release 3.0.0 since this is a big change in backward compatibility.

Telling everyone to switch from 'master' to 'main' before Git 3.0.0 comes out where 'main' is the default default branch name does not seem fair.

bernhold commented 3 years ago

Well, I believe that GitHub has already switched their default to main when you create a new repo there. However they did it. I don't know about other hosting sites.

bartlettroscoe commented 3 years ago

Well, I believe that GitHub has already switched their default to main when you create a new repo there. However they did it. I don't know about other hosting sites.

@bernhold, that only works if you let GitHub create the repo (usually an empty 'README.md' file). That does not work if you create your own local repo with raw Git and then push it to GitHub to finish the creation of the project (which is the most natural way to create a Git project). That inconsistency is what I worry about.

markcmiller86 commented 3 years ago

I found this useful article, https://stevenmortimer.com/5-steps-to-change-github-default-branch-from-master-to-main/.

In other contexts in which I participate, it is my impression there there is broad agreement on the imperative to replace slave everywhere and master when it is used with slave. However, there is less agreement on the imperative to replace master when used in isolation as there are numerous examples of its use (master-copy, scrum-master, mastering the skill of inclusive langauge, etc.) that have no historical roots in oppresive or genocidal systems.

That said, I see a qualitative difference between what a widely used tool such as git (or associated resource providers such as GitHub or GitLab) chooses as their default language (which most consumers simply adopt without question) for branch names (which, by the way, appears in all their or third party's online documentation and examples) and the choices individual projects make. I think it is a welcome step that GitHub changed its defaults.

For individual projects, I think if they use master together with slave or derivatives thereof as branch names, then IMHO, the same imperative to change branch names obviously exists. For projects that use master because it happened to be the default when they created the repo, the arguments to change it are not as strong. I suspect there is some motivation throughout the tech industry to do it more out of a sense of not looking bad in comparison with other projects who have opted to eliminate master as a branchname.

All that said, the proposed CC here was/would be to simply highlight for projects aiming to change branch names what is involved and what tools may be available to make it easy.

bartlettroscoe commented 3 years ago

My final comment on this is that if a majority of developers and users knew Git well enough, then making a transition like this would be a bunch of nothing. But is precisely because a majority of developers and users are very shaky with the usage of Git that, what should otherwise be a simple transition, will turn into a mess in many projects and will anger many developers and users.

bernhold commented 2 years ago

Should we change the default for this repo now (2021-2022 holiday period), while people aren't so active? I also sent an email to bssw-editorial

markcmiller86 commented 2 years ago

Should we change the default for this repo now (2021-2022 holiday period), while people aren't so active? I also sent an email to bssw-editorial

I am on the fence about this as previous comments probably elude. I think if we understand well (and document) why we are doing this, then I am fine with whatever choice we make.

rinkug commented 2 years ago

@markcmiller86 : update on this topic?

rinkug commented 2 years ago

Eat our own dogfood...using said resources to update branch names used in bssw repos.

Next step.

  1. Review github documentation about changing branch names and notify impacted people as best as we can. @bernhold will look into this.

Also once above step is done,

rinkug commented 1 year ago

We dont have resources right now to dedicate to this effort. We have 64 forks right now and will require some amount of effort.

Keeping this issue open for tracking in case this becomes a higher priority.

Revisit in 6 months around Aug 2023.

markcmiller86 commented 1 year ago

A possible useful resource, https://www.tidyverse.org/blog/2021/10/renaming-default-branch/

rinkug commented 1 year ago

We are in agreement in making this change. The timeline is what we are unsure of. Before we make any change, we need to figure out "implications" to outstanding PRs and to forks (do they get updated automatically?). Ross will try to look at this and get back to team and based on his findings we will figure out a timeline (or reassess feasibility).

bernhold commented 1 year ago

This is a continuation of the thread of this comment: https://github.com/betterscientificsoftware/bssw.io/issues/1164#issuecomment-1683150540

I see that there are currently 72 forks of this repository (https://github.com/betterscientificsoftware/bssw.io/forks). In principle, we could contact all of these people. However I think it would be tedious and I'm not sure it is worth it. Many are pretty far outdated, and would probably do just as well to blow away their current fork and make a new one.

Q1: what happens if we change our default branch and someone with an outstanding fork but no outstanding pull requests subsequently updates their fork with no additional special actions?

Q2: what happens if we change our default branch and someone with an outstanding pull request from their fork updates?

To me, the answers to these two questions strongly influence how we should handle informing forkers of the change (and which ones). Will things "just work"? Will they get incomprehensible error messages? Or something in between?

markcmiller86 commented 1 year ago

Will things "just work"? Will they get incomprehensible error messages? Or something in between?

I am not sure it matters that much. I suspect all but a few of those 72 forks are solved by your suggested action to blow away their current fork and make a new one. In the handful of cases where that isn't the easiest action (due to possible in-flight work), we could just have them contact us for help. I'd bet we get maybe one call.

bartlettroscoe commented 1 year ago

I see that there are currently 72 forks of this repository (https://github.com/betterscientificsoftware/bssw.io/forks).

@markcmiller86 and @bernhold, there is no good reason that I know of for why the main branch should be touched in a fork. The GitHub fork is for storing your topic branches so you can create PRs against the mainline branch in the root GitHub repo.

bernhold commented 1 year ago

But PRs target a specific branch of the parent repo -- the default branch unless you specify something else. So if we change our default branch to main and people have outstanding PRs against master, do they follow or do they break? And if they break, what has to be done to fix them? I think the numbers are small enough that we can work that issue individually, but it would be good to know what will happen and how to fix it if needed.

As to the general strategy of blowing away forks and making a new one: my concern here is what do the forkers see when they want to use (update) their fork again, for whatever reason? Is there some understandable error message that essentially says "blow this away and make a new fork"? Or is there some incomprehensible thing that requires a git expert to unpack? The former seems fine. The latter is a bit of a concern, though maybe we'd let it happen for the forks that haven't been updated recently.

bartlettroscoe commented 1 year ago

But PRs target a specific branch of the parent repo -- the default branch unless you specify something else. So if we change our default branch to main and people have outstanding PRs against master, do they follow or do they break? And if they break, what has to be done to fix them? I think the numbers are small enough that we can work that issue individually, but it would be good to know what will happen and how to fix it if needed.

@bernhold, yes but that is easy to fix. I change the target branch of a PR all the time (like when doing stacked PRs). It will take 15 mins for all of the outstanding PRs to bssw.io (of which there are only 10 currently).

As to the general strategy of blowing away forks and making a new one

@markcmiller86, do people really blow away their forks and re-create them? Why would they do that? (I guess those are the same people who are constantly deleting and re-cloning their local Git repos?)

rinkug commented 1 year ago

@bartlettroscoe

bartlettroscoe commented 1 year ago

I am working on putting together a PR that replaces all of the instances of 'master' with 'main' that need to be replaced. I need to get an idea of all of the files in the bssw.io repo mentioning the whole word 'master' (perhaps in a larger word with underscores '_' or dashes '-') that we many need to perform a renaming. I don't think we should look in the *.md articles themselves for now and instead just look at the process-related files that are impacted by looking in a few subdirs:

$ cd bssw.io/
$ find  .github Site docs images utils -type f -exec grep -l "[^a-zA-Z0-9]master[^a-zA-Z0-9]" {} \;
.github/PULL_REQUEST_TEMPLATE.md
.github/workflows/merge-master-to-preview.yml
.github/workflows/merge-pr-to-preview.yml
.github/workflows/no-prs-on-preview.yml
.github/workflows/README.md
Site/BSSwFellowshipProgram/People/NiemeyerKy.md
Site/BSSwFellowshipProgram/People/RobertsAmy_2021.md
Site/ContributeToBSSw.md
docs/js/jquery.navgoco.min.js
docs/pages/bssw/bssw_add_new_topics.md
docs/pages/bssw/bssw_author_guidelines_blog.md
docs/pages/bssw/bssw_blogworkflow.md
docs/pages/bssw/bssw_content_highlighting.md
docs/pages/bssw/bssw_content_metadata.md
docs/pages/bssw/bssw_content_placement.md
docs/pages/bssw/bssw_content_publishing.md
docs/pages/bssw/bssw_curatedworkflow.md
docs/pages/bssw/bssw_pr_preview_branch.md
docs/pages/bssw/bssw_styling_common.md
docs/pages/bssw/bssw_styling_curated.md
docs/pages/bssw/bssw_styling_event.md
docs/pages/bssw/bssw_styling_originalarticles.md
docs/pages/bssw/bssw_wikize_refs.md
docs/_config.yml
utils/convert_images_ref_to_rel_path.py
utils/tests/CMakeLists.txt
utils/tests/test_badlinks-wikized.md
utils/tests/test_badlinks.md
utils/tests/test_goodlinks-wikized.md
utils/tests/test_goodlinks.md
utils/tests/test_rerun_after_adding_link-wikized.md
utils/tests/test_rerun_after_adding_link.md
utils/tests/test_unused_linkdefs.md
utils/tests/test_wikizer-wikized.md
utils/tests/test_wikizer.md

And we need to look at the top-level files as well:

$ find . -maxdepth 1 -type f  -exec grep -l "[^a-zA-Z0-9]master[^a-zA-Z0-9]" {} \;
[empty]

That is more files that I thought and exposes how pervasive the main branch name is in a Git repo (which explains why the Git project still has not changed the default branch name from 'master' to 'main').

I will open each of these files up and change 'master' to 'main' everywhere it needs it.

bartlettroscoe commented 1 year ago

Things that need updated through the GitHub project site to change from 'master' to 'main':

The instructions given by GitHub to update the local branch name in log Git repos is:

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

I will carefully list what tasks need to be done and in which order once we decide to pull the trigger on this.

bartlettroscoe commented 1 year ago

FYI: The following PR that does all of the needed changes from 'master' to 'main':

You would merge this PR right after you change the default branch from 'master' to 'main' as described above.

bartlettroscoe commented 1 year ago

@bernhold, @rinkug, @markcmiller86, @betterscientificsoftware/bssw-editorial-board,

I think we are ready to pull the trigger on this. I updated the set of tasks in order above and it should go very quickly at this point.

Please let me know when you want for me to pull the trigger on this.

markcmiller86 commented 1 year ago

I defer to @bernhold and @rinkug

markcmiller86 commented 1 year ago

BTW...thanks @bartlettroscoe for all your work on this!

rinkug commented 1 year ago

We plan to do this in very early October 2023. @rinkug to contact Parallactic since they will have to make change immediately otherwise we lose access to production website updates.

bartlettroscoe commented 1 year ago

FYI: I just did the renaming of the default branch from 'master' to 'main' as described [above] and I just merged PR:

Now I need to make sure that PRs GitHub Actions workflows continue to work and send out email reminders.

bartlettroscoe commented 1 year ago

I also just updated the branch for the GitHub pages site from the 'docs' directory to the 'main' branch at:

bartlettroscoe commented 1 year ago

I sent out emails with the following instructions to both the IDEAS-ECP team and Clara and Matt:

The changes in the bssw.io GitHub repo should be complete. To update your local clones of the bssw.io GitHub repo, run the following git commits in your local bssw.io git repo (assuming your remote branch is called ‘origin’):

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

Please let me know if you have any problems with this.

-Ross

I ran those commands in my local Git bssw.io repo (but with 'origin' renamed to 'github') and it gives me the status:

$ git status
On branch main
Your branch is behind 'github/main' by 38 commits, and can be fast-forwarded.
  (use "git pull" to update your local branch)

nothing to commit, working tree clean

and the git pull worked fine and gave:

$ git log-short --name-status -1
05fe29e1 "Merge pull request #1803 from betterscientificsoftware/674-master-to-main"
Author: Roscoe A. Bartlett <rabartl@sandia.gov>
Date:   Mon Oct 2 15:06:29 2023 -0400 (18 minutes ago)
bartlettroscoe commented 1 year ago

FYI: Clara a Parallatic reports they have updated for the 'main' branch. Now we just need to test the rebuilds of the bssw.io site from an updated 'main' branch.

bartlettroscoe commented 1 year ago

FYI: Several updates to the 'main' branch since Monday have been made and recent rebuild of the main bssw.io site seem to be showing those updates. For example, PR

So that checks out.

bartlettroscoe commented 1 year ago

I think this Issue is ready to close. Any objections?

bartlettroscoe commented 11 months ago

I think this Issue is ready to close. Any objections?

This is done. See above.