Child pages
  • Removal of problematic language
Skip to end of metadata
Go to start of metadata

This page serves as a way to list any problematic language in the Sling codebases and the steps to remove it.

Discussion

Some of us think some terms like "master/slave, black/white list" should not be used anymore.

Opinions vary widely on this topic, mostly between a desire to be polite and non-offensive and on the other hand considering that words can have very different meanings depending on context.

Starting to use "better" terms for new things can be fairly easy (assuming we agree on what "better" means) but renaming existing things can be a lot of work, with potentially subtle effects on automated processes and backwards compatibility.

This page was created to evaluate the work needed to change existing terms, in order for the Sling PMC to make informed decisions, on whether the efforts and related benefits make sense.

External Sources

Github is moving its default branch to 'main' https://www.bbc.com/news/technology-53050955

Problematic Language?

We need to define what "problematic language" is.

In a recent interesting episode on the ASF Members list someone ironically mentioned "client/server" as being bad, and several people started discussing it seriously before realizing that it was ironic. Just because someone somewhere qualifies a given term as problematic doesn't make that true.

I think we need to make up our own (collective, Sling PMC) mind about which terms are actually problematic, to avoid wasting our time (and potentially causing trouble to our users) on things that are not worth those efforts.

Backwards compatibility?

Changes that break backwards compatibility are not desired in Apache projects, as per our maturity model (QU40).

This applies to changes in configuration parameter names and public API methods.

We need very good reasons to make changes that break compatibility in those areas, along with "bridges" to avoid breaking older code and systems.

A reasonable way to avoid such problems might be to create a "glossary of recommended terms" used for new code and in places where changes have no unwanted impact. And clearly explain in that document why we are not changing existing code in places where that would break backwards compatibility.

Topics

Rename 'master' Git branch

This branch can be renamed. One suggestion is to rename it to the 'main' branch although we should monitor what elsewhere is becoming the consensus on a new name for this branch.

Actions to take (potentially incomplete)

  • asking INFRA to change the default remote for 300+ repositories ( gitbox and github? )

    • gstein/INFRA says: our limit is (10) repositories. any changes to more than ten must be performed by a script, rather than human hands. the script to perform the change must be provided to Infra to review, then to execute. (iow, Infra will not develop such a script; 300 repositories was chosen by Apache Sling; Infra supports up to 10)
  • adjusting Jenkins tooling (and potentially Jenkins jobs)

  • evaluating whether we need to change something in SonarCloud

  • updating the 'repo' setup

  • updating documentation

  • asking everyone to update their local checkouts

  • needing to rebase (or drop!) existing PRs

Open questions:

  • what happens to links once we rename branches? Do they go stale or can we redirect?

Find problematic language in code and rename if possible

  • $ repo grep -i 'white *list'
    rename to ...
  • $ repo grep -i 'black *list'
    rename to ...
  • $ repo grep -i 'slave'
    rename to ...
  • $ repo grep -i 'master'
    rename to ...

We need to investigate if the rename has an impact on backward compatibility.

Actions to take

Proposal:

  • whitelist/blacklist should be changed to allowlist/blocklist
  • master/slave should be changed to primary/secondary

Open questions

Documentation changes

Problematic language

Any problematic language in the documentation on its own should be fixed.

Actions to take

...

Changes required because of code/git changes

Changes made in git and/or source code should be reflected in the associated documentation.

Actions to take

...

References

  • No labels