bssw-tutorial / tutorial-management

An issues-only repository for overarching management of BSSw tutorial development and presentation
0 stars 0 forks source link

Make the language in our tutorial more inclusive #14

Closed rinkug closed 2 years ago

rinkug commented 3 years ago

This is especially needed for the Git workflows that I presented at ISS21

bernhold commented 3 years ago

Can you be more specific about what is needed? Is it just the default branch names? Or other things too?

Note the following possibly related issues:

swoodeng commented 3 years ago

I'd like to help with this effort. Please let me know how I may participate.

bernhold commented 3 years ago

@swoodeng thanks for your interest! I think it would be useful to have you review our work. During today's tutorial, feel free to flag specific presentations (or other materials) that need updating. And later, maybe you'd be willing to review the new versions to ensure we've been thorough.

swoodeng commented 3 years ago

Thank you @bernhold, glad to help and I look forward to reviewing.

pagrubel commented 3 years ago

Should I do this in the presentation for SC? Will our example repo have a main branch? Does that matter?

bernhold commented 3 years ago

Pat, I think it would be great if you have time to make this change. It is easy to change the branch in the repo. I'm more concerned about ensuring that the graphics in the presentation that have "master" labels. I suppose you could probably create a bit of text to paste over them. Slide 7-12 look like they need this treatment. 16-22 should probably reflect the nomenclature the projects, even if they're still using "master".

pagrubel commented 3 years ago

I tried creating text to paste over them and couldn't get the text box to be opaque and/or come forward, not great with ppt apparently.

pagrubel commented 3 years ago

I figured it out

pagrubel commented 3 years ago

@bernhold I pushed a change, if you have time please check it. I will be editting possibly to add something about code review soon

bernhold commented 3 years ago

@pagrubel I've looked this over. I like what you've done.

I also checked out the outside resources we refer to for workflow examples. Turns out that GitLab Flow (slide 18) uses "main" instead of "master". So there is one instance on that slide that can be changed.

bernhold commented 3 years ago

@swoodeng I would appreciate your input on the remainder of the the cases where "master" appears in this presentation. At the moment, we're following the same terminology as the the outside documentation, which is still mostly "master" rather than "main".

I can imagine a couple of different approaches:

You, or others on the team, may have other ideas too.

swoodeng commented 3 years ago

@bernhold and @pagrubel, thank you for making changes to use more inclusive naming within the git tutorial. I suggest:

These changes will reduce the likelihood that the tutorial will need an update as outside resources adopt inclusive naming practices.

bernhold commented 3 years ago

Thanks @swoodeng , I think that makes sense. @pagrubel can you handle that? I can help if needed.

pagrubel commented 3 years ago

If you already have some verbage that would be great. Just put them in this issue and I’ll make a slide.

Pat

pagrubel commented 3 years ago

@pagrubel I've looked this over. I like what you've done.

I also checked out the outside resources we refer to for workflow examples. Turns out that GitLab Flow (slide 18) uses "main" instead of "master". So there is one instance on that slide that can be changed.

It also looks as though Git Flow uses main in their tutorial. I like their images also.

pagrubel commented 3 years ago

I am changing Git Flow, Github Flow and Gitlab Flow to main. I will leave Trilinos and OpenMPI since they still use master.

pagrubel commented 3 years ago

Ah I misread @swoodeng's suggestion. I will make a slide and change all to main.

bernhold commented 3 years ago

@pagrubel please let us know when you check in the new version. It would be great if @swoodeng and @markcmiller86 could review for us, particularly the slide about naming. Mark has also given this a lot of thought. Thanks

pagrubel commented 3 years ago

@bernhold @markcmiller86 @swoodeng I made a stab at making a slide. I'm wondering if I should add a statement about our support. Any suggestions will be appreciated.

Also now everytime I push I cringe: To github.com:bssw-tutorial/presentations.git bd3276b..7617da6 master -> master

markcmiller86 commented 3 years ago

@pagrubel can you provide context? Where should I be looking?

Also, as an aside, while the imperitave to address language like master when paired with slave is obvious (hopefully to everyone), the issues with master in isolation are, IMHO, less so. Many feel that proximity to the master/slave problem alone is reason enough and I honestly can't argue with that. But the truth is that master in isolation has numerous uses predating and unrelated to the genocide of slavery.

Yes, GitHub rolled out a big effort last year to change master to main but that was addressing their default language. Default language for a large organization like GitHub has far greater reach and pepertuation-potential than any one project and so I applauded GitHub's effort to change their defaults. And, where I can, I am making arguments to change master branchnames to something better like main or develop or whatever. But, I don't think the imperative for that is anywhere near as immediate as master together with slave and in cases where changing master (in isolation) presents real (not just percieved) difficulties, I think its ok to defer it.

All that said, I like the idea that we're changing our tutorial resources. At a minimum, we kinda sorta need to match GitHub's new default language :wink:.

bernhold commented 3 years ago

@markcmiller86 yes, right now we're talking about the git-workflows module, so the primary change is to use main instead of master in our presentation and hands-on instructions (there's a ticket to check/fix that too).

I can't think of any other language in the tutorial that would be considered discriminatory, but we need to always be paying attention to that.

pagrubel commented 3 years ago

@markcmiller86 and others Please look at slide 4: https://github.com/bssw-tutorial/presentations/blob/master/git-workflows.pptx

pagrubel commented 3 years ago

There is a mistake in the first sentence, it should read: Historically git repository platforms used the term master as the default branch for the main branch.

I'll change it after I get feedback since I will most likely change the slide anywan

markcmiller86 commented 3 years ago

Am sticking a revision of that slide here...

git-workflows-2-slide-4-mcm-revise.pptx

Some remarks...

Hopefully, you find the revision attached here useful.

markcmiller86 commented 3 years ago
  • The git tool then proliferated to GitHub and GitLab.

I am sorry, this reads like git drove the renaming. It didn't. I think GitHub actually drove the renaming and then GitLab and git itself quickly followed.

What I meant this to say was that git's choice of master as the default branch name prolifrated later to GitHub and GitLab.

markcmiller86 commented 3 years ago

Some other inclusivity musings regarding the git-workflow2.pptx slide deck...

pagrubel commented 3 years ago

I will look at these and fix

pagrubel commented 3 years ago

I think I'm done with the inclusivity part. If all agree we can close this issue. We may want to open another one for the names but for SC I suggest we leave Bob and Alice alone.

swoodeng commented 3 years ago

@pagrubel and @markcmiller86, thank you for your thoughtful work to update the tutorial. It reads clearly.

@markcmiller86, I agree that the use of the term master together with slave to label computer science constructs is more harmful to development teams than use of master alone.

In the context of git workflows, labeling a prominent branch master, imprints a development team's collaboration landscape with hierarchical and gender-biased concepts that do not accurately describe the interactions between branches in repositories. Continued use of this inaccurate term, when more accurate terms are available, tacitly endorses world views that stratify humanity into groups with restricted inter-communication.

Clear and open communication is a development team's greatest asset. Using accurate technical language without encumbrances of history or bias facilitates effective communication and efficient development.

markcmiller86 commented 3 years ago

In the context of git workflows, labeling a prominent branch master, imprints a development team's collaboration landscape with hierarchical

Yes, exactly. There is often a hierarchy to branches and selecting a branch naming scheme that captures that is wholly appropriate IMHO.

and gender-biased concepts

I am not familiar with any arguments relating master with gender bias. Can you provide some pointers so I can educate myself?

that do not accurately describe the interactions between branches in repositories.

If your looking for accuracy in descriptions, you might wanna try git branch --edit-description instead of the terse, often highly abbreviated branch names themselves, which tend to be rather short on characters. I think you'd find that even in repositories that don't use master (or other language you might find problematic) you would be hard pressed to understand the interaction between branches from their names. Thats why those branch diagrams used in the tutorial and tools for displaying them are so helpful.

Continued use of this inaccurate term, when more accurate terms are available, tacitly endorses world views that stratify humanity into groups with restricted inter-communication.

As above, if you have any pointers on how master (apart from being paired with trems like slave) has had or is having this effect, I would be happy to read up.

All that said, @swoodeng if you would like to continue this conversation apart from providing some helpful refs here, I do not think this issue is the place to do it. Please feel free to contact me via email.

swoodeng commented 3 years ago

https://www.merriam-webster.com/dictionary/master

bernhold commented 3 years ago

@pagrubel I would like to suggest a bit of a restructuring on slide 4 (and slide 3 will need to mirror the title of slide 4)

Names Matter

bernhold commented 3 years ago

I'm also now wondering if maybe we should move this slide to the intro module? That's the one at the very beginning that really just introduces the presenters, IDEAS, and a bit of the logistics (how to interact, hands-on activities, keeping in touch afterwards). I think it could be appropriate to say there that we strive for this tutorial to use inclusive language, with a couple bullets of explanation that is more general than the git default branch, and ask the audience to let us know about anything they feel is harmful or exclusionary. Along with the pointers to the INI site and the BSSw resource (which has a bit more background and additional links).

Thoughts?

markcmiller86 commented 3 years ago

ask the audience to let us know about anything they feel is harmful or exclusionary

Excellent idea IMHO. Also, including refs to INI is great idea.

pagrubel commented 3 years ago

I think for now we might want to keep it in git workflows, since some of the projects still use master and if they visit those sites during the talk or when they later see the slides, they will encounter master. If you feel a slide should also go in the intro I’m fine with that. What do other’s think?

Pat

pagrubel commented 3 years ago

I should have read that slide more thoroughly. I answered too quickly, yes put it in the intro and I'll get rid of it in git workflows.

bernhold commented 2 years ago

Confirmed that hands-on instructions are clean of concerning language. I think the last step will be to rename the default branches of a couple of our own repos as soon as we get past SC21.

bernhold commented 2 years ago

I've renamed the default branch in the presentations repo. As far as I know that was the last thing on our list. So I'm going to close this issue. If anyone discovers anything new we need to address, please create a new ticket.

In addition to the team, I'd like to particularly thank @swoodeng for both helping with this and holding us to account.