Scaffold repository tooling

[gziolo]

Initial setup for the repository was added with:

• chore: scaffold plugin entrypoint and tooling #4

Let’s coordinate remaining tasks in this issue:

• Prepare the composer package for publication and consumption by WordPress plugins.
• Decide whether to use namespaces in the plugin for Abilities API, replicate that in WP Core and how to use it in plugins with future compatibility in mind.
• Decide on the minimum required PHP version (7.4 vs 7.2).
• Fix remaining coding standards issues reported by CI (chore: scaffold plugin entrypoint and tooling #4 (comment)).
• Ensure CI checks run when landing PRs in trunk (chore: scaffold plugin entrypoint and tooling #4 (comment)).
• Audit ignoreErrors added to PHPStan (Add REST API controllers for Abilities API #6 (comment)).
• Audit excludes added for REST controllers in PHPCS (Add REST API controllers for Abilities API #6 (comment)).
• Upload the code coverage report for base (example message Add REST API controllers for Abilities API #6 (comment)).
• Ensure that CI jobs fail when unit tests fail (see example dev: use WP_Abilities_Registry::$instance instead of adding a new global #19 (comment)).

[justlevine]

• Fix remaining coding standards issues reported by CI (chore: scaffold plugin entrypoint and tooling #4 (comment)).
• Audit excludes added for REST controllers in PHPCS (Add REST API controllers for Abilities API #6 (comment)).

Advocating removing them entirely: https://github.com/WordPress/abilities-api/pull/15/files has PHPCS passing with intent.

[justlevine]

• Ensure CI checks run when landing PRs in trunk (chore: scaffold plugin entrypoint and tooling #4 (comment)).

#17 should fix this

[justlevine]

Going a bit out of technical order for logical cohesion:

• Audit ignoreErrors added to PHPStan

I think the broader question here is do we want to take advantage or turn off missingType.generics - not specific to REST.

• Pros: helps getting ahead of problematic api errors before they become unintended tech debt forever,
  but it also it also
• Cons: risks causing [one-time | release-process manual | release-process automated ] need to port our plugin into code.

That's more or less the same considerations as:

Decide on the minimum required PHP version (7.4 vs 7.2).

No need to rehash the PR description in #4 , but depending on the state of where PHP7.4 and/or PHPStan are in core by the time we're ready to merge means we might need to downgrade to merge.

Which segues us to:

• Prepare the composer package for publication and consumption by WordPress plugins.
• Decide whether to use namespaces in the plugin for Abilities API, replicate that in WP Core and how to use it in plugins with future compatibility in mind.

Or what I think is the real question: how are the plugins meant to be consumed?

If the plugin is meant to be used and adopted before a (theoretical) merge to core (eg REST API), approach and needs are different than if we're just iterating here quickly before a short-term merge to core (e.g. individual Performance plugins) versus if it'l take some sort of "canonical" shape where it needs to live and exist alongside it (a la Gutenberg).

• Namespaces/prefixes let us "move fast and break things" without bringing tech debt into core / schisming adoption, but need a but of forethought to limit the contributor work if ongoing syncs w. core are required.
• A "plugin" approach means the only Composer release step is someone w. perms generating some packagist tokens, a "dependency" approach in WordPress either limits short-term adoption or requires some "latest-version library" boilerplate like Action Scheduler uses.
• Decisions like is the PHP 7.4 <-> 7.2 a hassle, and do we want to use @phpstan-* annotations also differ based on the above.

---

Y'all A8C folks are the ones that need to guide this but if my hunch is correct that we're shooting for a "ready-or-not" 7.0 merge into core, after which iteration will happen in core directly or the specific Experiments (since this repu is just the underlying api), then my recommendation is:

1. We leave things at PHP 7.4 until we're ready to merge. Only once we are actually ready to merge, in the unlikely even thatif Matt still hasnt greenlit 7.4, then we downgrade to 7.2 in that PR and call it a day.
2. Samesies on PHPStan generics, array shapes, etc. Unless the concern is that it will block contributors to this repo, downgrading/stripping out @phpstan-* specific types is a one-time, pre-merge decision, if core hasn't gotten there yet.
3. We prefix/namespace. It lets us iterate on API shape, our MCP and Experiments maintain active development, and even start fostering an ecosystem (that's moving faster than ever and why we're all here), and lets us make a clean break into core without needing to schlepp in all that fast-moving tech debt with us. Be this a one-time core adoption or a "Canonical plugin", Prefixes/namespaces let us hollow out this plugin into a b/c adapter as [X] gets moved into core with no baggage.

[justlevine]

And after than entire dissertation, @JasonTheAdams tells me that we're trying to get this into core for 6.9, and not 7.0 😅, per the 6.9 Roadmap,

So yeah, in that case I recommend:

• No PHPStan generics anywhere.
• Yes PHPStan array shapes, we can strip them on final merge but they're essential to help validate our API shape.
• PHP 7.4 in our requires + tooling, so we can use the best. PHP 7.2 in our linting/stanning so the port to core can be easy if matt doesn't change his mind.
• Only "composer" requirement is how to install a wordpress-plugin using composer. A quick CI to build the dist version on a release (without the docs/bins) would be nice but nonessential, since it's only expected to stick around for the next few months.
• No prefixes/namespaces, this isn't meant to live outside and hang around on people WP sites.

[JasonTheAdams]

@justlevine I'm curious why the usage of PHPStan generics is discouraged?

[justlevine]

@JasonTheAdams only in the context of this specific repo, and the 6.9 merge target. IMO:

• PHPStan needs to come to WP core before generics do. There isn't too much surface area here that would benefit from us implementing our own generics even if we didnt need to strip them out before a core-wp merge, but if there is a good candidate, we can cross that bridge when we come to it (and who knows, maybe generics will be allowed in core by then too).

• The particular generics that PHPStan are warning about (and suppressed in Add REST API controllers for Abilities API #6) are coming from the phpstan-wordpress extension, which stubs in generics on WP_REST_Request (e.g).. Since this code is meant for core (where those generics arent enforced) and we need to manually validate any array shapes before we use them anyway, the internal type-hinting inside a couple *Rest_Controller:some_function() doesn't seem to add much benefit either.

[JasonTheAdams]

Thanks for the explanation! To be clear, in your mind does this pertain to custom generics (i.e. @template), or the use of all generics (e.g. @param array<string, int>)?