69 lines
4.5 KiB
Markdown
69 lines
4.5 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 workflow (`.gitea/workflows/pr.yml`, replaces `pr-version-check.yml`)
|
|
|
|
Jobs (all required checks on `main`):
|
|
1. `version-changelog` - unchanged logic (version bump + changelog heading). Keep this job/workflow name so the existing required context `version-changelog / version-changelog (pull_request)` keeps working, or update protection when renamed.
|
|
2. `validate` - install `shopware-cli`, `extension validate .` (hard gate, no `|| true`).
|
|
3. `package` - `extension package` with `--git-commit "$GITHUB_SHA"`, then assert the zip contains built admin JS (`Resources/public/administration/js`) when an admin entry exists.
|
|
4. `phpunit` - `composer create-project shopware/production` (6.6.x) + MariaDB service, symlink plugin, install/activate, run phpunit. PHP 8.3.
|
|
|
|
### Release workflow (`.gitea/workflows/release.yml`)
|
|
|
|
On push to `main`, guarded against re-release by an existing tag:
|
|
validate -> `extension package --git-commit "$GITHUB_SHA"` -> **validate the zip** -> 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.
|