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

[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.

[metodiew]

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?

[SergeyBiryukov]

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.

[DrewAPicture]

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.

[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

[DrewAPicture]

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]

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]

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

[pento]

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]+[^.]"

[metodiew]

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!

[SergeyBiryukov]

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.

[metodiew]

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

[pento]

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?