Replace the `$new_whitelist_options` variable with a more inclusive name

[desrosj]

Branching this off of #50413.

The global variable $new_whitelist_options should be replaced with a more inclusive name. Because this is a global that a ​handful of plugins reference directly, care should be taken when renaming it.

I propose renaming the current variable (something like $new_allowed_options), but maintaining the current variable for a period of time (maybe two releases?), and triggering a _doing_it_wrong() notice.

[desrosj]

In 48121:

General: Remove “whitelist” and “blacklist” in favor of more clear and inclusive language.

“The WordPress open source community cares about diversity. We strive to maintain a welcoming environment where everyone can feel included.”

With this commit, all occurrences of “whitelist” and “blacklist” (with the single exception of the $new_whitelist_options global variable) are removed. A new ticket has been opened to explore renaming the $new_whitelist_options variable (#50434).

Changing to more specific names or rewording sentences containing these terms not only makes the code more inclusive, but also helps provide clarity. These terms are often ambiguous. What is being blocked or allowed is not always immediately clear. This can make it more difficult for non-native English speakers to read through the codebase.

Words matter. If one contributor feels more welcome because these terms are removed, this was worth the effort.

Props strangerstudios, jorbin, desrosj, joemcgill, timothyblynjacobs, ocean90, ayeshrajans, davidbaumwald, earnjam.
See #48900, #50434.
Fixes #50413.

[ayeshrajans]

I suppose the least disruptive approach would to $new_whitelist_options = &$new_allowed_options, and submit tickets in relevant plugins to update the variable. This should add almost zero impact in terms of performance/memory usage because the $new_whitelist_options shim is just a reference to the new variable name.

Another way would be to convert $new_allowed_options to an ArrayAccess implementation, and emit a deprecation notice every time an array key is accessed. This would require us to declare a new class and populate it, which can be take more resources for a feature that we eventually need to phrase out.

[ayeshrajans]

Submitting a patch that replaces the variable with $new_allowlist_options, and creates a reference of it at $new_whitelist_options. Unless a plugin goes out of its way to destroy the variable (which will only destroy the reference with the patch), this should seamlessly rename the variable.

This is the first approach I mentioned in comment 2.

[ayeshrajans]

Please ignore the previous patch. It had a missing @since annotation that is fixed in this file.

Deprecate the old $new_whitelist_options variable in favor of $new_allowed_options and pass by reference.

Trac ticket: https://core.trac.wordpress.org/ticket/50434

[desrosj]

I was having issues with 50434.2.patch​ applying cleanly so I recreated the changes in a PR on GitHub attached to the ticket above.

I removed the inline @deprecated documentation tag where the variable was passed by reference. I could not find any other instances in Core where something had a @deprecated tag inline, except action and filter hooks.

Based on an ​initial scan of the plugin directory, it does not seem like this change should be too problematic. A lot of the instances being flagged on that search are caused by the plugin bundling the WPCS sniffs, which includes checks for the variable.

@ayeshrajans I did have one question on the patch. What is the need to pass the new variable by reference in unregister_setting()? Is this to ensure that if a a plugin or theme manually erases and repopulates the global the setting is correctly unregistered?

[jorbin]

I wonder if we might want to introduce a _deprecated_global function to properly warn folks. I also think it would fantastic if we could remove the global all together rather than rename it.

[desrosj]

@jorbin is there any prior history to look to where a global has been deprecated and removed in Core?

Where I dropped the ball and forgot to circle back to this before beta 1, I think a more conservative approach like the one in the current patch would be best for 5.5, and maybe we could outline the plan to add _deprecated_global() and officially deprecate $new_whitelist_options in 5.6?

[SergeyBiryukov]

Replying to desrosj:

I think a more conservative approach like the one in the current patch would be best for 5.5, and maybe we could outline the plan to add _deprecated_global() and officially deprecate $new_whitelist_options in 5.6?

Makes sense to me.

Noticed a couple of typos in the PR:

• $new_whiltelist_options (extra "l") in the @since note.
• The inline comments should start with /*, not /** (the latter is for proper DocBlocks).

Looks good otherwise.

[desrosj]

In 48477:

General: Rename the $new_whitelist_options global variable.

This change renames $new_whitelist_options to $new_allowed_options. This makes the variable’s purpose more clear, and promotes using more inclusive language.

For backwards compatibility, the new variable is passed by reference to the old one.

Follow up to [48121].

Props ayeshrajans, desrosj, jorbin, SergeyBiryukov.
See #50413.
Fixes #50434.

This was merged into WordPress Core in https://core.trac.wordpress.org/changeset/48477.

[justinahinon]

Dev note link: ​https://make.wordpress.org/core/2020/07/23/codebase-language-improvements-in-5-5/