This page serves as a way to list any problematic language in the Sling codebases and the steps to remove it.
Table of Contents | ||
---|---|---|
|
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
In addition to gstein's note above, there is no API to change the the default branch name, so in practice we have no way of performing the change.
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
After checking out Sling as documented at https://github.com/apache/sling-aggregator/
- $ repo grep -i 'whitelistwhite *list'
rename to ... - $ repo grep -i 'blacklistblack *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.
Alternatively, look into the reports from https://clc.diversity.apache.org/ .
Actions to take
Proposal:
whitelist
/blacklist
should be changed toallowlist/
blocklist
...
master/slave
should be changed toprimary/secondary
Open questions
- how should we handle API that is affected? See for instance https://github.com/apache/sling-org-apache-sling-discovery-base/tree/master/src/main/java/org/apache/sling/discovery/base/connectors/ping/wl
- how should we handle metatype entries that are affected?
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
...
Completed and planned work items
Jira | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
|