Openj9: Replacing master/slave with more inclusive terms

Created on 3 Jul 2020 · 11Comments · Source: eclipse/openj9

Due to recent events and in alignment with IBM's emb(race) pledge the IBM style guide has recently flagged certain words as "do not use" list for public content such as:

Instead of using: blacklist & whitelist
use: blocklist & allowlist

Instead of using: master & slave
use:

coordinator/controller/leader/main/manager/parent/primary
worker/child/helper/replica/secondary

Since OpenJ9 feeds into IBM J9 I think it makes sense to adopt this language here as well.

I noticed that the terminology master/slave threads are used quite a bit in gc code. I'm happy to make the changes for this but can someone more familiar with that area advise on what words make the most sense to use as alternates?

Source

theresa-m

👎1 👍1

All 11 comments

Thanks for opening this issue @theresa-m. This is the right thing to do and I'm glad you've started the discussion here.

A number of discussions have been quietly happening around this and similar topics including changing the name of the master branch in all OpenJ9 repos (@keithc-ca) and using referring to Jenkins's machines as nodes or workers (@AdamBrousseau).

In discussion with @amicic & @dmitripivkine, we agreed to rename the GC Slave threads to be GC Worker threads, and the master gc thread to the main gc thread. It makes sense to start with the thread names as they are visible in javacores, and then work through removing the other uses in the code.

Code changes can start immediately. PRs for name changes should target changing names and avoid additional refactorings to speed review and merge processes.

Branch name changes should wait until after the 0.21.0 release is complete to avoid any delays to the release.

DanHeidinga on 3 Jul 2020

👍1

For whitelist/blacklist I've replaced some uses in DDR: https://github.com/eclipse/openj9/pull/10076

@AdamBrousseau fyi there are WHITE_LIST & copyright_whitelist in the copyright check, I'll leave that to you so I don't break anything

theresa-m on 3 Jul 2020

Yes, thank you Theresa. I have on my list to update all the code under buildenv. We have many candidates.

AdamBrousseau on 3 Jul 2020

👍1

This is my non buildenv/branch name list:

[x] remove whitelist/blacklist: https://github.com/eclipse/openj9/pull/10076
[x] remove whitelist/blacklist OMR https://github.com/eclipse/omr/pull/5393
[x] request changes from zlib https://github.com/madler/zlib/pull/511
[x] omr rename MasterGCThread to MainGCThread: https://github.com/eclipse/omr/pull/5384 https://github.com/eclipse/openj9/pull/10139
[x] omr + openj9 dependent slave/master replaces https://github.com/eclipse/openj9/pull/10174 https://github.com/eclipse/omr/pull/5398
[x] master/slave refactors:
- [x] Java8andUp Test_Object https://github.com/eclipse/openj9/pull/10160
[x] remaining gc slave/master openj9 replacements https://github.com/eclipse/openj9/pull/10217
[x] openj9 JCL: masterlock->mainlock https://github.com/eclipse/openj9/pull/10217
[x] Xgc:finalizeSlavePriority and Xgc:finalizeMasterPriority= https://github.com/eclipse/openj9/pull/10230

docs:

[x] docs update: https://github.com/eclipse/openj9-docs/issues/605 https://github.com/eclipse/openj9-docs/pull/612
[x] docs api update: https://github.com/eclipse/openj9-docs/issues/607 https://github.com/eclipse/openj9-docs/pull/618

openj9 blogs:

[x] replacements in blog posts to avoid confusion (edit: couldn't find any uses of gc/vm structs or method names that need changing)

theresa-m on 3 Jul 2020

@theresa-m Please create a docs issue for any updates that might be necessary as a result of code changes. I can't see much that's likely, except "slave" - see below.
I have already made the following changes, which should be visible after 0.21.0 GA:
0x "whitelist" or "blacklist"
1x "master" in xtgc.md : ("master thread" --> "main thread")
4x "slave" in tool_jdmpview.md not changed: These occur in some sample output, but I assume that output will need to be regenerated as a result of code changes.

pmhayward on 16 Jul 2020

👍1

I have some commits drafted. The one I am struggling with is master, particularly "Jenkins Master" and anytime we're referencing the main branch of a repository. For the branch names I don't think we can change most of these instances as things will break or doc won't make sense. For Jenkins Master, that is Jenkins' defined term. Not that we _can't_ call it something else like main or primary, but nobody will know what we're talking about. Maybe I'm not being open minded about it.

AdamBrousseau on 29 Jul 2020

Hopefully Jenkins will update their terminology too. In the mean-time, we can use the term 'controller', or something else suitable, with a foot-note in the documentation explaining the translation. Outside that foot-note, though, everything should be consistent.

Github plans to make 'main' the default branch name, but there's nothing that says we can't change our branch names now.