WordPress.org

Make WordPress Core

Opened 6 weeks ago

Closed 13 days ago

#48255 closed defect (bug) (fixed)

Consistent deprecation of action and filter hooks

Reported by: jrf Owned by: SergeyBiryukov
Milestone: 5.4 Priority: normal
Severity: normal Version: 5.3
Component: General Keywords: has-patch
Focuses: docs, coding-standards Cc:
PR Number:

Description

While testing a new sniff for WPCS, I ran into an number of inconsistencies regarding hook deprecation.

In particular:

  • Over 30 deprecated hook call not using the do_action_deprecated()/apply_filters_deprecated() functions.
  • Not using {@see ...} for the replacement in the @deprecated tag, meaning the Dev handbook won't automatically link to the replacement.
  • Hook documentation not being in the most logical place for the hook.
  • This filter is documented in ... comments not using short docblock style.
  • A few deprecated hook calls in tests using version numbers which don't comply with the x.x.x version format.

The attached patches would fix these inconsistencies.

Related: #41121, #48252, #48254

Attachments (5)

48255-deprecated-hooks-use-the-correct-function.patch (18.1 KB) - added by jrf 6 weeks ago.
Use the correct function for deprecated hooks
48255-deprecated-hooks-improve-documentation.patch (17.3 KB) - added by jrf 6 weeks ago.
Deprecated hooks: improve documentation Let the docs link to the replacement when available.
48255-deprecated-hooks-correct-placement-of-hook-documentatio.patch (2.6 KB) - added by jrf 6 weeks ago.
Documentation: correct placement of hook documentation x 2
48255-deprecated-hooks-use-short-docblock-style.patch (2.6 KB) - added by jrf 6 weeks ago.
Documentation: use short docblock style comments for "filter documented elsewhere" comments
48255-deprecated-hooks-tests-use-x.x.x-style-version-nrs.patch (3.3 KB) - added by jrf 6 weeks ago.
[Tests] Deprecated hooks: use x.x.x style version numbers

Download all attachments as: .zip

Change History (14)

@jrf
6 weeks ago

Use the correct function for deprecated hooks

@jrf
6 weeks ago

Deprecated hooks: improve documentation Let the docs link to the replacement when available.

@jrf
6 weeks ago

Documentation: correct placement of hook documentation x 2

@jrf
6 weeks ago

Documentation: use short docblock style comments for "filter documented elsewhere" comments

@jrf
6 weeks ago

[Tests] Deprecated hooks: use x.x.x style version numbers

#1 @netweb
6 weeks ago

  • Milestone changed from Awaiting Review to 5.4

Although the majority of the proposals here are docs only changes a couple of patches are not, hence adding to 5.4 rather than late in the 5.3 milestone cycle

#2 @SergeyBiryukov
13 days ago

In 46684:

Coding Standards: Consistently use do_action_deprecated() and apply_filters_deprecated() for deprecated hooks.

Props jrf.
See #48255.

#3 @SergeyBiryukov
13 days ago

In 46685:

Docs: Use the {@see ...} tag for the replacement in @deprecated tags, so that Developer Reference could automatically link to the replacement.

Props jrf.
See #48255.

#4 @SergeyBiryukov
13 days ago

In 46686:

Coding Standards: Revert the change to wp-includes/class-wp-xmlrpc-server.php in [46684] to investigate unit test failures.

See #48255.

#5 @SergeyBiryukov
13 days ago

In 46687:

Coding Standards: Fix WPCS issue in [46684].

See #48255.

#6 @SergeyBiryukov
13 days ago

Looking at [46686] and the failures it fixed, it appears that while the enable_xmlrpc option was deprecated in [21804] / #21509, the pre_option_* and option_* filters added there for backwards compatibility are not deprecated, so apply_filters_deprecated() should not be used there.

#7 @SergeyBiryukov
13 days ago

In 46688:

Docs: Correct the documentation placement for wp_print_styles and shortcode_atts_{$shortcode} hooks.

Props jrf.
See #48255.

#9 @SergeyBiryukov
13 days ago

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

In 46689:

Docs: Use 3-digit, x.x.x style semantic versioning for $version argument in do_action_deprecated() and apply_filters_deprecated() calls.

Props jrf.
Fixes #48255.

Note: See TracTickets for help on using tickets.