Change the "Blacklist / Whitelist" nomenclature

[tlfeng]

Goal of the enhancement

Coming from #2589

Replace non-inclusive terminologies "blacklist" and "whitelist" throughout this repository with inclusive ones.

Context

What is “inclusive language”?

Inclusive language is designed to avoid excluding people on the basis of gender, sexual preference, age, race, ability, etc. By using language that avoids expressions which imply or express ideas that have prejudice to any particular group of people, we aim to create a more equitable community.

Why using “inclusive language” is important?

Using inclusive language helps build an inclusive environment, which accepts diversity and ensures any individuals and groups feel welcome, respected, and safe. Diversity does contribute to create a fair and strong organization, and also leads to diversity of ideas, which change into creativity and innovation.

How to apply “inclusive language” in a software program?

Replace “objectionable language in code bases and documentation. It involves assessing existing code bases and documentation, identifying potentially problematic language, then replacing terms with more preferable language.

Solution

Overview

To solve the issue, breaking changes will be introduced to OpenSearch, which requires backwards compatibility. The exclusionary terms exist in APIs and configurations, which will impact the compatibility with previous versions of OpenSearch and its third-party clients and tools.
We will support both and new APIs or configurations for a period of time, to let users get used to the breaking changes gradually. Considering OpenSearch follows Semantic Versioning, we are going to include the new API and configuration in current minor versions, while continuing to provide support for the previous APIs and configurations for a period of time, then remove support for the old ones in a next major version.

Substitute for the exclusionary terminology

Our proposed preferable terminologies:

1. Use allowlist to replace whitelist
2. Use denylist to replace blacklist

Location for the terminologies:

• code comments
• internal variable, method and class names
• Gradle build environment configuration
• field, method, class and package names that are exposed as API in Java libraries (renaming will impact clients and plugins that depend on OpenSearch code base)
• setting names and values (including definition, yml configuration files)
• tests

Versions to introduce the change

• Add the new usages with inclusive terminology and deprecation notice for the old usages in minor versions of 1.x.
• Remove the support for the old usages (APIs and settings) in a major version, it could be either 2.0 or 3.0.

Explanation:

1. The ideal case is to apply inclusive naming to replace the exclusionary terminology as soon as possible, but the backwards compatibility is a key aspect to be considered, so with new usages added soon, the old usages will be kept for a while before removal to keep the compatibility.
2. Considering OpenSearch follows Semantic Versioning, deprecation notice MUST come at a minor version, and the breaking change, such as API removal MUST come at a major version.
3. Update in March 2022: In practice, new usages will be added in version 2.0, and old usages will be removed in at least version 3.0.

Procedure for the replacement

1. Replace the exclusionary words that won’t impact the compatibility.

(source of the idea)
Replace all the exclusionary words in the following location:

• code comments
• Internal variable, method and class names
• Gradle build environment configuration

2. Deprecate old usages that having exclusionary words and impact the compatibility, then create alternative usages with the inclusive terms.

(source of the idea)
This step includes the following effort:

1. Deprecate the setting which contains exclusionary words.
2. Add proper form of deprecation notice for every setting changes, including in code (such as adding @Deprecated annotation), console output and logs.
3. Create alternative settings where having name change, so that calls to the new names can have the same effect with the old names.
4. For settings, adding fallback logic to fallback to the existing setting with old name, when the corresponding new setting is not configured.

The location that will impact the compatibility when changed:

• Configuration, including setting name.

3. Add tests to check both old and new usages - in Settings.

(source of the idea)
Adding new unit tests to check the both old and new names have got the same functionality.

4. Replace the exclusionary words in log messages and update documentation.

This step includes the following effort:

1. Replace the exclusionary words in logs.
2. Update the user and developer documents to introduce the new usages, and notice the deprecation of old usages.

5. Replace the exclusionary words that will impact software programs depend on OpenSearch Java libraries - in Java APIs.

Replace the exclusionary words in all Java APIs, including field, method, class, and package names.
The "Java APIs" refers to those packaged in Java libraries and are published to Maven (https://search.maven.org/search?q=g:org.opensearch https://mvnrepository.com/artifact/org.opensearch)
Impact of this step:
All plugins, clients and tools that use OpenSearch Java APIs from OpenSearch Java libraries which contain non-inclusive terminologies have to make corresponding changes to call new APIs, if they want to upgrade the dependency to a future major version of OpenSearch.

6. Remove the deprecated settings in a future major version.

Sub-issues

• Replace "blacklist/whitelist" terminology in code comments, and internal variable, method and class names #1484
• Add alternative usage for the configuration that contains "blacklist/whitelist" terminology #1547
• Replace "blacklist / whitelist" terminology in Gradle build environment configuration  #2458
• Replace "blacklist/whitelist" terminology in Java APIs #1683
• Remove the usages with non-inclusive language.

Appendix

Location that contains the exclusionary terms and will impact the compatibility when changed

Settings
1 reindex.remote.whitelist (static)
Code: https://github.com/opensearch-project/OpenSearch/blob/1.0.0/modules/reindex/src/main/java/org/opensearch/index/reindex/TransportReindexAction.java#L60

Location that contains the exclusionary terms and will impact software programs depend on OpenSearch Java libraries

API of Java library
1 Painless SPI - multiple classes with name “Whitelist”
Code: https://github.com/opensearch-project/OpenSearch/tree/1.0.0/modules/lang-painless/spi/src/main/java/org/opensearch/painless/spi
Javadoc: https://opensearch.org/javadocs/1.0.0/OpenSearch/modules/lang-painless/spi/build/docs/javadoc/org/opensearch/painless/spi/package-summary.html

Related issues and PRs

Existing PR before the issue created: #744
Related issue: #472

Issues for other repositories in the organization:

• [FEATURE] Change the "blacklist / whitelist" nomenclature documentation-website#449
• Change the "Blacklist / Whitelist" nomenclature sql#464
• Deprecate the "Blacklist / Whitelist" nomenclature security#1665
• Change the "Blacklist / Whitelist" nomenclature alerting#321
• Deprecate the "Blacklist / Whitelist" nomenclature OpenSearch-Dashboards#1319

[stockholmux]

Hey - just noticed that this was on the roadmap for 1.3 yet it's marked "breaking." The body of this issue does describe what's happening but if you just look at the roadmap it's alarming to see "breaking" on a minor release.

Can we remove that tag?

[dblock]

@stockholmux I think we want the non-breaking changes in 1.3, so for now I removed breaking instead.