haylanandClaude Bot
ff69377749
- drop the separate validate job (the zip is validated after packaging); same in release - shared scripts/ci/assert-built-assets.sh (BusyBox-safe), now also used by release - actions/cache for npm, shopware-cli and composer - phpunit: shopware-cli image instead of a 4.5 min apt install; MariaDB 10.11 (11.4 broke Shopware's migrations: Duplicate column 'sorter_key') - protect-main.sh: drop the removed validate context Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
69 lines
4.8 KiB
Markdown
69 lines
4.8 KiB
Markdown
# Spec: Shopware plugin guideline compliance (build/release pipeline)
|
|
|
|
Outcome of the Wayfinder map `.scratch/shopware-guideline-compliance/` (tickets 01-05; research evidence
|
|
on branches `research/shopware-guideline-checklist`, `research/shopware-cli-ci-behaviour`,
|
|
`research/gitea-28-pipeline-standards`). Target: **Store-ready** artifacts, published to Gitea only
|
|
(Gitea Release + Composer registry). Uploading to the Shopware Store is out of scope.
|
|
|
|
## 1. Principles
|
|
|
|
- Workflows are **plugin-agnostic**: no plugin name, package name, owner, repo or host is hard-coded;
|
|
all derive from `composer.json` and the `gitea` context. The same files must work unchanged for a
|
|
second plugin and be extractable to Gitea's shared-workflow repository later.
|
|
- One artifact: the `shopware-cli extension package` zip (prebuilt admin/storefront JS) is used for
|
|
both the Gitea Release asset and the Composer registry.
|
|
- `shopware-cli` is intentionally **unpinned** (`latest`). Known tradeoff: a CLI release can turn PRs
|
|
red without a repo change; treat that as a signal to fix config.
|
|
- `RELEASE_TOKEN` is the only token (release, assets, registry publish, link). Workflows still declare
|
|
`permissions:`.
|
|
|
|
## 2. Plugin changes
|
|
|
|
| # | Change |
|
|
|---|--------|
|
|
| P1 | Commit `src/Resources/config/plugin.png` (256x256). Do not ship `plugin-transparent.png`. |
|
|
| P2 | Logging: monolog channel `aeon_dump_manager` (`Resources/config/packages/monolog.yaml`, `build()` in the plugin class loading `packages/*.yaml`); inject `monolog.logger.aeon_dump_manager` into `PurgeDumpsTaskHandler`, `DumpService`, `CreateDumpHandler`; log dump job start/finish/failure. |
|
|
| P3 | Migrate `services.xml` -> `services.yaml` and `routes.php` -> `routes.yaml`. No validation ignore for this. Update the "XML services" rule in `CLAUDE.md`. |
|
|
| P4 | `composer.json`: `php` -> `^8.2`. Verify Shopware 6.6's own PHP requirement. |
|
|
| P5 | Delete the empty lifecycle overrides in `AeonDumpManager`; keep `uninstall`. |
|
|
| P6 | `.config/shopware-extension.yml` for build excludes and validation settings (add ignores only for real, accepted findings). |
|
|
| P7 | Keep Keep-a-Changelog `CHANGELOG.md`; verify with a local `shopware-cli extension package --release` how the changelog is read. |
|
|
|
|
## 3. Pipeline
|
|
|
|
### PR workflows
|
|
|
|
Jobs (all required checks on `main`):
|
|
`pr-version-check.yml` (job `version-changelog`) is unchanged apart from `permissions:`; its name keeps the existing required context. New `plugin-checks.yml`:
|
|
|
|
1. `package` - `extension package` with `--git-commit "$GITHUB_SHA"`, `extension validate` on the resulting zip (hard gate; replaces a separate directory validate, which only repeats those checks), then `scripts/ci/assert-built-assets.sh` (built admin/storefront JS present when sources exist). All shopware-cli jobs run in `ghcr.io/shopware/shopware-cli:latest`; npm and shopware-cli caches via `actions/cache`.
|
|
2. `phpunit` - `composer create-project shopware/production` (6.6.x) + MariaDB service, copy the plugin into `custom/plugins`, install/activate, run phpunit. Runs in the same `shopware-cli` image (PHP and Composer included; `shivammathur/setup-php` hangs on this runner and apt installs cost ~4.5 min). MariaDB 10.11, because 11.4 broke Shopware's own migrations.
|
|
|
|
### Release workflow (`.gitea/workflows/release.yml`)
|
|
|
|
On push to `main`, guarded against re-release by an existing tag:
|
|
`extension package --git-commit "$GITHUB_SHA"` -> **validate the zip** -> assert built assets -> create the Gitea
|
|
release via API (`POST /repos/{owner}/{repo}/releases`, creates the tag) with the zip as asset ->
|
|
upload the same zip to the Composer registry -> link package to repository.
|
|
Removes the manual `git tag` step, the `akkuman` action and the `git archive` zip. Packaging happens
|
|
before the tag exists, so a failed build leaves no orphan tag.
|
|
|
|
### Branch protection (one-time, manual)
|
|
|
|
`scripts/protect-main.sh` using `tea api PATCH repos/{owner}/{repo}/branch_protections/main` to set the
|
|
required status-check contexts (current: `version-changelog / version-changelog (pull_request)`; add
|
|
the new PR jobs). `tea branches protect` cannot set status checks. Not run by the pipeline.
|
|
|
|
## 4. Open items to verify while implementing
|
|
|
|
- Release POST creates a missing tag (fallback: tag step after packaging).
|
|
- Meaning of HTTP 400 on the package-link endpoint.
|
|
- Whether bare `validate` runs PHPStan/ESLint (needs PHP/Node on the runner); Node availability on the runner image.
|
|
- Accepted size for `metadata.icon.size`; error-vs-warning rule list of validate.
|
|
- Whether `routes.php` is flagged by validate; `shopware-cli extension fix` correctness for the YAML migration.
|
|
- Exact status-check context names of the new jobs (set after the first run).
|
|
|
|
## 5. Out of scope / later
|
|
|
|
Shopware Store upload; Gitea shared-workflow repository; phpunit lowest-version matrix; Store listing metadata.
|