From 64a53efc88588f1c19e1ee5167cb97c7b295bf62 Mon Sep 17 00:00:00 2001 From: Chris Huber Date: Sun, 21 Jun 2026 11:15:37 -0400 Subject: [PATCH] Harden php-transformer release metadata --- .github/workflows/php-transformer.yml | 42 +++++++++++++++++++ php-transformer/README.md | 12 ++++++ php-transformer/composer.json | 5 +++ php-transformer/composer.lock | 2 +- .../docs/consumer-prs/packaging.md | 2 + 5 files changed, 62 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/php-transformer.yml diff --git a/.github/workflows/php-transformer.yml b/.github/workflows/php-transformer.yml new file mode 100644 index 0000000..2ca50c5 --- /dev/null +++ b/.github/workflows/php-transformer.yml @@ -0,0 +1,42 @@ +name: PHP Transformer + +on: + pull_request: + paths: + - ".github/workflows/php-transformer.yml" + - "php-transformer/**" + push: + branches: + - trunk + paths: + - ".github/workflows/php-transformer.yml" + - "php-transformer/**" + +jobs: + validate: + name: Composer validate and test + runs-on: ubuntu-latest + + defaults: + run: + working-directory: php-transformer + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + php-version: "8.1" + coverage: none + tools: composer:v2 + + - name: Install dependencies + run: composer install --no-interaction --prefer-dist --no-progress + + - name: Validate Composer package metadata + run: composer validate --strict + + - name: Run package tests + run: composer test diff --git a/php-transformer/README.md b/php-transformer/README.md index c6531d3..29484f3 100644 --- a/php-transformer/README.md +++ b/php-transformer/README.md @@ -138,6 +138,8 @@ Run the package contract and parity fixtures with `composer test`. The checked-i The package lives in a subtree of the Blocks Engine repository. Composer cannot discover a package whose `composer.json` is below the repository root from a plain monorepo VCS tag. After release, consumers need either a subtree-split/Packagist package whose root is `php-transformer/`, or an explicit Composer `package` repository that points at the release archive and maps autoloading to the subtree. +This package intentionally omits `replace` and `provide` declarations for the older downstream package names. Those packages expose their own WordPress plugin bootstraps, functions, hooks, CLI commands, abilities, and product-shaped reports, so the canonical transformer package should not satisfy their Composer requirements directly. + Preferred downstream constraint once the package is published through Packagist or a subtree-split repository: ```sh @@ -180,6 +182,16 @@ If the first release is only available as a Blocks Engine monorepo archive, down Before the first tag is available, review branches may use a Composer VCS or path repository with an inline alias. Merge-ready downstream PRs should replace those review-only constraints with one of the no-local-path release shapes above. +### Release Readiness Checklist + +Before tagging the first package release: + +- Run `composer validate --strict` and `composer test` from `php-transformer/`. +- Confirm `VERSION`, `php-transformer.php`, and the intended tag all resolve to `0.1.0`. +- Confirm Packagist or the subtree split indexes `php-transformer/` as the package root, not the repository root. +- Confirm downstream merge candidates use `automattic/blocks-engine-php-transformer:^0.1.0` instead of path repositories, unpublished branches, or inline aliases. +- Keep the transformer metadata free of downstream wrapper package names, `replace`, and `provide` declarations. + Homeboy owns the local release preflight for this package through `php-transformer/homeboy.json`. The only version target is `VERSION`, currently `0.1.0`; release automation should tag from the package subtree after the upstream PRs are merged, without adding wrapper-package names to this package metadata. Recommended post-merge dry-run: diff --git a/php-transformer/composer.json b/php-transformer/composer.json index 2536495..f7ae179 100644 --- a/php-transformer/composer.json +++ b/php-transformer/composer.json @@ -50,5 +50,10 @@ "php": "8.1.0" }, "sort-packages": true + }, + "extra": { + "branch-alias": { + "dev-trunk": "0.1.x-dev" + } } } diff --git a/php-transformer/composer.lock b/php-transformer/composer.lock index c1214d0..cb27ec8 100644 --- a/php-transformer/composer.lock +++ b/php-transformer/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "36b0edf59764b0d63e80ad192c53ef8c", + "content-hash": "3472ba768651b23c423f2b2e29b22c43", "packages": [ { "name": "dflydev/dot-access-data", diff --git a/php-transformer/docs/consumer-prs/packaging.md b/php-transformer/docs/consumer-prs/packaging.md index 2d16cf6..23ce665 100644 --- a/php-transformer/docs/consumer-prs/packaging.md +++ b/php-transformer/docs/consumer-prs/packaging.md @@ -138,6 +138,8 @@ Downstream wrappers must support their current unprefixed development installs. The first tagged release should be `0.1.0` unless maintainers choose a repo-wide release scheme before merge. +The package does not declare a Composer `version` field. Composer derives immutable release versions from tags; the checked-in `VERSION` file and plugin header are Homeboy release targets that should match the first tag. The `dev-trunk` branch alias is only a pre-release convenience for review and Packagist metadata, not a substitute for the first `0.1.0` tag. + Release readiness preflight before tagging: ```sh