Arrays/ArrayDeclarationSpacing: add new property and soft-deprecate old one

[rodrigoprimo]

Description

Adds a new allow_single_item_single_line_explicit_key_arrays property to the WordPress.Arrays.ArrayDeclarationSpacing sniff and soft-deprecates the old allow_single_item_single_line_associative_arrays property to align the property name with the "explicit keys" terminology introduced in #2688.

For now, the old property continues to work via a backward compatibility layer: if the new property has not been changed from its default value and the old property has, the old property's value is used. The plan is to remove the old property in the next major release.

This is a soft deprecation (docblock and changelog only) as suggested in #2691 (comment). We are considering adding a runtime deprecation warning in the last release before the next major.

Besides that, this PR includes a separate commit that moves an intentional parse error test to its own file.

Suggested changelog entry

Deprecated

• WordPress.Arrays.ArrayDeclarationSpacing: the allow_single_item_single_line_associative_arrays property has been deprecated in favor of allow_single_item_single_line_explicit_key_arrays.

Additional notes

If this PR is merged:

• https://github.com/WordPress/WordPress-Coding-Standards/wiki/Customizable-sniff-properties should be updated to document the new property name.
• I suggest creating an issue to centralize everything that needs to be addressed in the last release before 4.0, starting with hard-deprecating allow_single_item_single_line_associative_arrays.

Related issues/external references

Closes: #2691

[jrfnl]

Hi @rodrigoprimo,

Thanks for working on this. This looks good to me, aside from some nitpicking.

Besides that, this PR includes a separate commit that moves an intentional parse error test to its own file.

I understand why you made that change in this PR, but that change has a different decision point, so could have been merged already if pulled separately (ahead of this change).

I suggest creating an issue to centralize everything that needs to be addressed in the last release before 4.0, starting with hard-deprecating this allow_single_item_single_line_associative_arrays.

I'd suggest creating two new issues:

1. To hard-deprecate the old property in the last WPCS 3.x release (also see my notes about how to do this in #2691)
2. To remove the old property in WPCS 4.0.

[jrfnl]

I'm trying to think of a shorter name which is still descriptive enough and failing.

@GaryJones @dingo-d Have either of you got any suggestions ?

If not, I'm okay with leaving it at what it currently is. Just feels clunky and if we do want to change the name, now would be the time.

[GaryJones]

Let's leave it as is. There are alternatives, but I'm not convinced by any of them for various reasons.

[rodrigoprimo]

Thanks for your review, @jrfnl! I addressed the points that you raised.

I'd suggest creating two new issues:

• To hard-deprecate the old property in the last WPCS 3.x release (also see my notes about how to do this in Arrays/ArrayDeclarationSpacing: how to deprecate the allow_single_item_single_line_associative_arrays property? #2691)
• To remove the old property in WPCS 4.0.

I agree with your proposal to create two different issues.

My original plan was to create a generic issue where we can track everything that needs to be hard-deprecated in the last WPCS 3.x release (for now, only the property soft-deprecated in this PR, AFAIK) instead of creating an issue just for this property. Similarly, I would then create an issue to track everything that needs to be removed in the WPCS 4.0 release, and not an issue just to remove this one property. Does this approach make sense? I'm asking because it's not clear to me from your comment whether you prefer two specific issues just for allow_single_item_single_line_associative_arrays, or if the broader approach I have in mind is fine.

[jrfnl]

it's not clear to me from your comment whether you prefer two specific issues just for allow_single_item_single_line_associative_arrays, or if the broader approach I have in mind is fine.

From a maintainer point of view, I don't have a strong preference either way (as I'd always have to open the tickets anyway to make sure the right thing gets addressed).

From an end-user point of view, I think I'd prefer separate issues for separate deprecations/removals as that way when looking at the 4.0 milestone, I could just "scan the headlines" to get a quick overview of what to expect instead of having to open the issue and dig into the fine print to figure out what will change.

Does that help ?

[jrfnl]

Save for the discussion regarding a potential namespace for the new property as per #2696 (comment), I'm happy with this PR.

[rodrigoprimo]

Squashed the review changes into the original commit and force-pushed.

[jrfnl]

FYI: In light of this PR now having been merged, I've re-milestoned everything merged so far from the 3.3.x milestone to the 3.4.0 milestone, as the introduction of a new property and deprecation of another belong in a minor, not a patch version.

[rodrigoprimo]

Just documenting that I created the two follow-up issues to hard-deprecate and then remove the old property (#2704 and #2705).

Regarding updating the wiki with the new property name once 3.4.0 is released, do you think the note in the release checklist to check whether the wiki needs updating is sufficient?

[jrfnl]

@rodrigoprimo Feel free to update the wiki already. That should ensure we don't forget (and the "Available since" info should prevent confusion for end-users anyway).

[rodrigoprimo]

Done, thanks!

[jrfnl]

Done, thanks!

@rodrigoprimo Uh..oh .... you seem to have removed the old property from the table. This is wrong as it means that people on an older version of WPCS can no longer find the information they need about the old property.

The docs should contain both the info about the old + the new property, with annotations about when each were added and when the first was deprecated.
The information about the "old" property should only be removed once WPCS 5.0.0 comes out.

[rodrigoprimo]

I removed the information about the old property from the table, but added a note to document its deprecation. I did not consider that in the wiki we want to keep information for users of older versions of WPCS. I have made a new update, adding the old property back to the wiki. Let me know if it looks good now.

[jrfnl]

I removed the information about the old property from the table, but added a note to document its deprecation. I did not consider that in the wiki we want to keep information for users of older versions of WPCS. I have made a new update, adding the old property back to the wiki. Let me know if it looks good now.

@rodrigoprimo Thanks for that. I've tweaked the section a little more to be more in line with other property renames, which are annotated throughout the page.