AeonDumpManager/docs/spec/shopware-guideline-compliance.md

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 the Gitea Release asset; the Composer registry gets the same content repacked root-level (the registry needs composer.json at the zip root, see section 4).
• 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): plugin-checks.yml (the former pr-version-check.yml was deleted; version-changelog is now a job in it):

0. version-changelog - version bump vs main and matching CHANGELOG heading.

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 (now plugin-checks / version-changelog|package|phpunit (pull_request), set on main). tea branches protect cannot set status checks. Not run by the pipeline.

4. Open items (status after the first pipeline run)

• Release POST creates a missing tag: resolved - the POST created the tag and release for v0.1.0 (release id 55).
• Meaning of HTTP 400 on the package-link endpoint: open (not evidenced yet).
• Whether bare validate runs PHPStan/ESLint; Node availability on the runner image: open (not evidenced; the zip validate passes in the shopware-cli image).
• Accepted size for metadata.icon.size; error-vs-warning rule list of validate: resolved - validate on the zip reports "No problems found", so the icon size is accepted.
• Whether routes.php is flagged by validate: resolved - not flagged ("No problems found"). shopware-cli extension fix correctness for the YAML migration: open.
• Exact status-check context names: resolved - final: plugin-checks / version-changelog (pull_request), plugin-checks / package (pull_request), plugin-checks / phpunit (pull_request), set on main.
• Finding: the Composer registry rejected the shopware-cli zip with "composer.json file is missing"; Gitea needs composer.json at the zip root, while the shopware-cli zip nests everything in a top-level folder. Fix (implemented separately): repack the zip with the top-level folder stripped for the registry upload; the Release asset stays the shopware-cli zip.

5. Out of scope / later

Shopware Store upload; Gitea shared-workflow repository; phpunit lowest-version matrix; Store listing metadata.