WordPress.org

Make WordPress Core

Opened 4 years ago

Closed 3 years ago

Last modified 3 years ago

#36495 closed defect (bug) (fixed)

Standardize on 3-digit x.x style for _doing_it_wrong() and _deprecated_function() calls

Reported by: SergeyBiryukov Owned by: metodiew
Milestone: 4.6 Priority: normal
Severity: trivial Version:
Component: General Keywords: good-first-bug has-patch needs-refresh
Focuses: docs Cc:
PR Number:

Description (last modified by SergeyBiryukov)

We generally use 2-digit x.x style for _doing_it_wrong() calls, e.g. '4.5' instead if `'4.5.0'.

I've counted 5 instances of '4.5.0' being passed to _doing_it_wrong() and _deprecated_function().

We use 3-digit x.x.x style for @since, per the documentation standards, however for _doing_it_wrong() and _deprecated_*(), 2-digit x.x style seems to prevail.

We should standardize on 3-digit x.x.x style throughout core.

Attachments (2)

36495.diff (135.3 KB) - added by metodiew 4 years ago.
36495.2.diff (135.5 KB) - added by metodiew 4 years ago.
I think I've missed a few places, so here's an updated patch

Download all attachments as: .zip

Change History (16)

#1 follow-up: @metodiew
4 years ago

Do we need to remove the 3rd digit for older version, e.g:

src/wp-includes/post.php
3389: _doing_it_wrong( __FUNCTION__, sprintf( __( 'Invalid taxonomy: %s.' ), $taxonomy ), '4.4.0' );

or 4.5.x is enough?

#2 in reply to: ↑ 1 ; follow-up: @SergeyBiryukov
4 years ago

  • Focuses docs added

Replying to metodiew:

Do we need to remove the 3rd digit for older version?

Yes, previous instances should also be corrected. I've found some instances of 4.3.0, 4.2.0, and 4.1.0 as well.

I see how it might be confusing though, as we do use 3-digit x.x.x style for @since, per the documentation standards, however for _doing_it_wrong() and _deprecated_*(), 2-digit x.x style seems to prevail.

I guess we should standardize it one way or the other for _doing_it_wrong() and add a note to the handbook.

#3 in reply to: ↑ 2 @DrewAPicture
4 years ago

  • Keywords needs-patch added

Replying to SergeyBiryukov:

I guess we should standardize it one way or the other for _doing_it_wrong() and add a note to the handbook.

I've always thought it was weird that we used two-digit x.x style for _deprecated_*() and _doing_it_wrong() calls. It's probably rare that we'd add such a call in a point release, at the same time, I'm +1 to standardize on the three-digit x.x.x style throughout core.

#4 follow-up: @metodiew
4 years ago

I would love to go over all instance of _doing_it_wrong() and _deprecated_*() and update them if we agree on one standard that would be used in the future versions

#5 in reply to: ↑ 4 @DrewAPicture
4 years ago

  • Keywords good-first-bug added
  • Owner set to metodiew
  • Status changed from new to assigned

Replying to metodiew:

I would love to go over all instance of _doing_it_wrong() and _deprecated_*() and update them if we agree on one standard that would be used in the future versions

Let's do it and see what a patch looks like.

Assigning the ticket to mark the good-first-bug as "claimed"

@metodiew
4 years ago

#6 @metodiew
4 years ago

Here is the initial version of the patch I'm working on. I've replace all instances of _doing_it_wrong() and _deprecated_*() I found.

Please, review this and let me know if we need to update/fix/improve something else and I'll work on a new patch

@metodiew
4 years ago

I think I've missed a few places, so here's an updated patch

#7 @Presskopp
3 years ago

  • Keywords has-patch added; needs-patch removed

#8 @pento
3 years ago

  • Keywords needs-refresh added
  • Milestone changed from Awaiting Review to Future Release

Nice work, @metodiew!

36495.2.diff needs a refresh, it doesn't apply cleanly against trunk anymore. (_wp_upload_dir_baseurl() was removed in [37676].)

Also, there's been a new incorrect _deprecated_function() call added in wp-includes/ms-deprecated.php.

For reference, this command helped when looking for other incorrect calls:

ack -C4 '(_deprecated_|_doing_it_wrong)' | ack "['\"][1-4]+\\.[0-9]+[^.]"

#9 @SergeyBiryukov
3 years ago

  • Description modified (diff)
  • Summary changed from Use 2-digit x.x style for _doing_it_wrong() and _deprecated_function() calls to Standardize on 3-digit x.x style for _doing_it_wrong() and _deprecated_function() calls

#10 @metodiew
3 years ago

Thanks @pento!

I'll refresh the patch against the latest trunk version.

I've used ack only with the string search, but your suggestion seems to be very helpful!

#11 @SergeyBiryukov
3 years ago

  • Resolution set to fixed
  • Status changed from assigned to closed

In 37985:

Docs: Use 3-digit, x.x.x-style semantic versioning for _doing_it_wrong(), _deprecated_function(), _deprecated_argument(), and _deprecated_file() throughout core.

Props metodiew.
Fixes #36495.

#12 @SergeyBiryukov
3 years ago

  • Milestone changed from Future Release to 4.6

#13 @metodiew
3 years ago

I'm a bit confused here. The ticket was committed and closed with props. (Not that I mind :))

However, I'm more than happy to refresh the patch before the release date and make sure we have the inline documentation updated

#14 @pento
3 years ago

It's cool, @SergeyBiryukov took care of refreshing it. We had a beta release today, so we wanted to get as many tickets closed as possible! Under normal circumstances (when there isn't a tight deadline), we would've let you clean up the patch, so you get the full experience. ;-)

I only see one incorrect @since comment, so I'll fix that up in a moment. Were there any other ones that you'd noted?

Note: See TracTickets for help on using tickets.