Chore: Configure the composer package for publishing #35

gziolo · 2025-08-21T10:49:04Z

Closes Scaffold repository tooling #13.

Prepare the composer package for publication and consumption by WordPress plugins.

For complete transparency, I reused some of the configurations from:

I also used AI (GitHub Copilot coding agent) extensively to configure everything so it works both as a WP plugin and shares only includes through Composer. I avoided using namespaces to keep things simplified and used autoload.files to bootstrap all necessary files.

Testing

Some checks that I executed

Validate composer config

composer validate --no-check-publish

Result contained deprecation notices and a success message:

./composer.json is valid

Files included in the git archive

echo "Total tracked files:" && git ls-files | wc -l && echo "\nFiles in git archive (respecting .gitattributes export-ignore):" && git archive --format=tar HEAD | tar -tf - | wc -l && echo "\nFiles excluded from archive (tracked but export-ignored):" && comm -23 <(git ls-files | sort) <(git archive --format=tar HEAD | tar -tf - | sort) | sed -n '1,200p' && echo "\nFiles explicitly in archive (sample):" && git archive --format=tar HEAD | tar -tf - | sed -n '1,200p'

Result

Total tracked files:
      40

Files in git archive (respecting .gitattributes export-ignore):
      22

Files excluded from archive (tracked but export-ignored):
.editorconfig
.gitattributes
.github/workflows/copilot-setup-steps.yml
.github/workflows/release.yml
.github/workflows/test.yml
.gitignore
.nvmrc
.prettierignore
.prettierrc.js
.wordpress-org/.gitkeep
.wp-env.json
composer.lock
package-lock.json
package.json
phpcs.xml.dist
phpstan.neon.dist
phpunit.xml.dist
tests/_output/.gitkeep
tests/bootstrap.php
tests/unit/abilities-api/wpAbilitiesRegistry.php
tests/unit/abilities-api/wpRegisterAbility.php
tests/unit/rest-api/wpRestAbilitiesInit.php
tests/unit/rest-api/wpRestAbilitiesListController.php
tests/unit/rest-api/wpRestAbilitiesRunController.php

Files explicitly in archive (sample):
.wordpress-org/
CONTRIBUTING.md
LICENSE.md
README.md
abilities-api.php
composer.json
docs/
docs/1.intro.md
docs/2.getting-started.md
docs/3.registering-abilities.md
docs/4.using-abilities.md
includes/
includes/abilities-api.php
includes/abilities-api/
includes/abilities-api/class-wp-abilities-registry.php
includes/abilities-api/class-wp-ability.php
includes/bootstrap.php
includes/rest-api/
includes/rest-api/class-wp-rest-abilities-init.php
includes/rest-api/endpoints/
includes/rest-api/endpoints/class-wp-rest-abilities-list-controller.php
includes/rest-api/endpoints/class-wp-rest-abilities-run-controller.php

Copilot

Pull Request Overview

This PR configures the WordPress Abilities API package for publication and consumption as a Composer package. The changes prepare the codebase for distribution by establishing proper autoloading, removing embedded hooks, and adding distribution configuration.

Adds Composer autoload configuration with a bootstrap file for automatic class and function loading
Removes embedded WordPress action hooks from library classes to allow consumer control
Configures Git attributes to exclude development files from distributed packages

Reviewed Changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
composer.json	Adds autoload configuration, updates metadata, and reorganizes structure for package distribution
includes/bootstrap.php	New bootstrap file that conditionally loads core classes and functions for Composer autoloading
abilities-api.php	Replaces direct file includes with Composer autoloader detection and moves hook registration
includes/rest-api/class-wp-rest-abilities-init.php	Removes embedded WordPress action hook to allow consumer control
.gitattributes	Configures export-ignore rules to exclude development files from distributed packages

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

abilities-api.php

gziolo · 2025-08-21T11:41:29Z

composer.json

 			"phpstan/extension-installer": true,
 			"composer/installers": true
-		}
+		},


I moved a few things around, so the order is similar to https://github.com/WordPress/php-ai-client/blob/trunk/composer.json. That made auditing easier for me.

.gitattributes

jeffpaul · 2025-08-21T13:48:54Z

The composer.json changes look ok to me, left some comments on the .gitattributes file where I think we can simplify it in a couple places.

justlevine

Quick test of git archive shows we're getting the desired outcome.

Some nits in the gitattributes that only matter if someone wants to use the file as prior art, but considering the 6.9 merge and that anybody using a release version and not a dev-* branch will get the GH release .zip, they can probably be ignored.

git archive --format=tar HEAD -o repo.tar && tar -tf repo.tar


.wordpress-org/
CONTRIBUTING.md
LICENSE.md
README.md
abilities-api.php
composer.json
docs/
docs/1.intro.md
docs/2.getting-started.md
docs/3.registering-abilities.md
docs/4.using-abilities.md
includes/
includes/abilities-api.php
includes/abilities-api/
includes/abilities-api/class-wp-abilities-registry.php
includes/abilities-api/class-wp-ability.php
includes/bootstrap.php
includes/rest-api/
includes/rest-api/class-wp-rest-abilities-init.php
includes/rest-api/endpoints/
includes/rest-api/endpoints/class-wp-rest-abilities-list-controller.php
includes/rest-api/endpoints/class-wp-rest-abilities-run-controller.php

.gitattributes

abilities-api.php

felixarntz

@gziolo Overall this looks solid to me, though I have a high level question about the approach in #13 (comment) - why do we want to publish this on Packagist (vs having it as a plugin on .org and thus also on wpackagist.org)?

gziolo · 2025-08-22T09:38:26Z

why do we want to publish this on Packagist (vs having it as a plugin on .org and thus also on wpackagist.org)?

I responded in the issue. The short version is that, for now, I was willing to replicate how WP Feature API was structured for distribution, and it turns out they offered a Composer library. I updated the config to reflect it in 55fab93.

I addressed all the feedback. This is what I see in the archive fter executing git archive --format=tar HEAD -o repo.tar && tar -tf repo.tar:

Should we also exclude the top-level abilities-api.php, which is an entry point for the WP plugin?

justlevine · 2025-08-22T12:34:58Z

composer.json

 	"license": "GPL-2.0-or-later",
-	"type": "wordpress-plugin",
-	"version": "0.1.0",
+	"type": "library",


Strongly disagree with this change. Nothing prevents anybody from using a wordpress-plugin as a library. But if anybody (including MCP Adapter or Experiments) tries to test this using Composer as a plugin dependency, they can't if it's a library.

https://github.com/WordPress/abilities-api/pull/42/files#r2294029457

justlevine · 2025-08-22T12:40:38Z

Should we also exclude the top-level abilities-api.php, which is an entry point for the WP plugin?

Please give me time to test using abilities-api.php instead of adding bootstrap.php, and some of the other changes here that IMO should be necessary for this to be used as a Composer library, don't make sense in our context (versus the WP Feature API prior art), and might even be detrimental to adoption and usage both in the next 3 months and in the post-6.9-merge cleanup.

emdashcodes · 2025-08-22T14:54:33Z

why do we want to publish this on Packagist (vs having it as a plugin on .org and thus also on wpackagist.org)?

I responded in the issue. The short version is that, for now, I was willing to replicate how WP Feature API was structured for distribution, and it turns out they offered a Composer library. I updated the config to reflect it in 55fab93.

Our main goal for this in the Feature API was to make it possible for plugins to bundle the Feature API as a dependency, without the end user needing to install a separate plugin. This was the reason for the version loader as well.

justlevine · 2025-08-22T15:34:06Z

Hey @gziolo et-al please take a look at #42 which reverts the "type": "library" to type:wordpress-plugin and includes documentation showing how it can still be including as a Composer library (even if the Feature API considerations may not necessarily apply here).

Jameswlepage · 2025-08-27T15:22:51Z

Felix, Jeff, and I had a chat about the wordpress-plugin vs library type discussion. Let's go with the library type to unblock things, mainly so other plugins like Elementor/Woo/Hosting MU etc can include this as a traditional package. This decision is made in part with the understanding that this will go core in 6.9, so we’re treating this as a transitional setup.

We recognize the concern that calling it a library may limit some Composer use cases (e.g., plugin dependencies). However, since wordpress-plugin can still be consumed as a library but not always vice versa, we’ll document usage patterns clearly so consumers understand the intended workflows. If needed, we can revisit the package type once the 6.9 merge has landed and the distribution model stabilizes.

For now, prioritizing unblock and compatibility with large plugin ecosystems outweighs the downside, and the configuration should make adoption easier in the short term while keeping a path open for refinement later.

justlevine · 2025-08-27T15:31:26Z

Let's go with the library type to unblock things, mainly so other plugins like Elementor/Woo/Hosting MU etc can include this as a traditional package.

This is a false premise. Elementor/Woo/Hosting MU can all use something with a "type": "wordpress-plugin" same way they can if it's type "library".

However, since wordpress-plugin can still be consumed as a library but not always vice versa, we’ll document usage patterns clearly so consumers understand the intended workflows.

To me this reads like a justification for using wordpress-plugin. If it does everything that a library does, why go with the intentionally limiting one that requires additional documentation?

For now, prioritizing unblock and compatibility with large plugin ecosystems outweighs the downside, and the configuration should make adoption easier in the short term while keeping a path open for refinement later.

This also seems like a false premise. What becomes "unblocked" or "compatible" by using "library" over "wordpress-plugin" , and how does the configuration make adoption easier in the short term?

Added version definition for the plugin and improved comments.

codecov · 2025-08-28T07:18:19Z

Codecov Report

❌ Patch coverage is 0% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.43%. Comparing base (3ad7a38) to head (a5e4bee).
⚠️ Report is 1 commits behind head on trunk.

Files with missing lines	Patch %	Lines
includes/bootstrap.php	0.00%	10 Missing ⚠️
abilities-api.php	0.00%	3 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##              trunk      #35      +/-   ##
============================================
- Coverage     89.82%   88.43%   -1.39%     
  Complexity       94       94              
============================================
  Files             7        8       +1     
  Lines           511      519       +8     
============================================
  Hits            459      459              
- Misses           52       60       +8

Flag	Coverage Δ
unit	`88.43% <0.00%> (-1.39%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

gziolo · 2025-08-28T07:39:18Z

I rebased this branch and applied a couple of small fixes based on the work shared by @justlevine in #42. Taking into account the decision to go with type library in Composer, is there anything missing in this PR before we land it and create a git tag with v0.1.0 release?

justlevine

is there anything missing in this PR before we land it

lgtm 🚀

and create a git tag with v0.1.0 release?

Not strictly necessary for a v0.1.0, but do you want me to backport the relevant doc changes from #42 into a new PR?

gziolo · 2025-08-28T12:34:18Z

Not strictly necessary for a v0.1.0, but do you want me to backport the relevant doc changes from #42 into a new PR?

That would be very helpful!

gziolo self-assigned this Aug 21, 2025

gziolo added the [Tool] Issues related to development tooling, such as linting, testing, or CI label Aug 21, 2025

gziolo requested review from Copilot, emdashcodes and justlevine August 21, 2025 10:49

Copilot AI reviewed Aug 21, 2025

View reviewed changes

abilities-api.php Show resolved Hide resolved

gziolo mentioned this pull request Aug 21, 2025

Scaffold repository tooling #13

Closed

9 tasks

gziolo commented Aug 21, 2025

View reviewed changes