Make WordPress Core

Opened 4 years ago

Closed 4 years ago

Last modified 4 years ago

#50434 closed defect (bug) (fixed)

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

Reported by: desrosj's profile desrosj Owned by: desrosj's profile desrosj
Milestone: 5.5 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch commit has-dev-note
Focuses: Cc:


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.

Attachments (2)

50434.1.patch (4.3 KB) - added by ayeshrajans 4 years ago.
50434.2.patch (4.3 KB) - added by ayeshrajans 4 years ago.
Please ignore the previous patch. It had a missing @since annotation that is fixed in this file.

Download all attachments as: .zip

Change History (14)

#1 @desrosj
4 years ago

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.

#2 @ayeshrajans
4 years ago

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.

#3 @ayeshrajans
4 years ago

  • Keywords has-patch added; needs-patch removed

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.

4 years ago

4 years ago

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

This ticket was mentioned in PR #397 on WordPress/wordpress-develop by desrosj.

4 years ago

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

Trac ticket:

#5 @desrosj
4 years ago

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?

#6 @jorbin
4 years ago

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.

#7 follow-up: @desrosj
4 years ago

@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?

#8 in reply to: ↑ 7 @SergeyBiryukov
4 years ago

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.

#9 @desrosj
4 years ago

  • Keywords commit needs-dev-note added

#10 @desrosj
4 years ago

  • Owner set to desrosj
  • Resolution set to fixed
  • Status changed from new to closed

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.

desrosj commented on PR #397:

4 years ago

This was merged into WordPress Core in

#12 @justinahinon
4 years ago

  • Keywords has-dev-note added; needs-dev-note removed
Note: See TracTickets for help on using tickets.