From 5f8cc9bdadcc50e4c29b2efb4a5cd72c882a250a Mon Sep 17 00:00:00 2001 From: ArthurErlich Date: Sun, 4 Oct 2026 00:49:42 +0200 Subject: [PATCH] docs: refresh CLAUDE.md and compliance spec after guideline PR Co-Authored-By: Claude Sonnet 5.5 --- CLAUDE.md | 29 ++++++++++++++++++++-- docs/spec/shopware-guideline-compliance.md | 28 ++++++++++++--------- 2 files changed, 43 insertions(+), 14 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 634eee2..c7e7ce8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,7 +20,9 @@ the full build spec live under `.scratch/admin-dump-manager/` and `.scratch/dump - Plugin store-config UI fields (e.g. `maxDumps`, `retantionDays`) are defined in `src/Resources/config/config.xml` and read at runtime via Shopware's SystemConfigService. - `src/Resources/app/administration/` holds the admin UI module (Vue-based Shopware Administration - extension), currently just the `swag-example` scaffold module. + extension). The `aeon-dump-manager` module (`src/module/aeon-dump-manager/`) provides the list page + (`page/aeon-dump-manager-list`), en-GB/de-DE snippets and ACL privilege roles (`acl/`: `viewer`, + `creator`, `deleter`); `src/service/dump-api.service.ts` is the client for the dump API routes. ## Running the plugin @@ -51,6 +53,10 @@ activates this plugin inside a real Shopware kernel for the test run (`KERNEL_CL `Shopware\Core\Kernel` in `phpunit.xml`). This means tests require a working Shopware installation/DB to bootstrap against — they are not runnable as an isolated PHP package. +In CI (`phpunit` job) a Shopware 6.6 project is prepared once (`composer create-project` + phpunit, +cached monthly), the plugin is copied into `custom/plugins`, and `system:install` runs once into +`shopware_test` (MariaDB 10.11 service), so the bootstrapper only activates the plugin. + ```bash vendor/bin/phpunit # full suite vendor/bin/phpunit --filter TestClassName # single test class @@ -59,10 +65,29 @@ vendor/bin/phpunit tests/SomeTest.php # single file ## Dependencies -- PHP `^8.1`, `shopware/core` `~6.6.0` (from `composer.json`); `phpunit/phpunit` `^10.0` as the only +- PHP `^8.2`, `shopware/core` `~6.6.0` (from `composer.json`); `phpunit/phpunit` `^10.0` as the only dev dependency. - PSR-4 autoload: `AeonDumpManager\` → `src/`, `AeonDumpManager\Tests\` → `tests/`. +## CI / release pipeline + +Gitea workflows in `.gitea/`, plugin-agnostic (name/version come from `composer.json`). `shopware-cli` +runs from its official Docker image, intentionally unpinned (`latest`): a red build after a CLI release +means fix the config. + +- `workflows/plugin-checks.yml` (PRs into `main`) has three jobs: `version-changelog` (every PR into + `main` must bump `composer.json` version and add a matching `## [x.y.z]` CHANGELOG heading), `package` + (shared composite action `actions/package`: `shopware-cli extension package`, `extension validate` on + the zip, `scripts/ci/assert-built-assets.sh`), and `phpunit`. The package job caches the tested zip + keyed by the commit's tree hash. +- `workflows/release.yml` (push to `main`, serialized, skipped if tag `v` exists): reuses the + cached zip when the tree hash matches (else packages again, always re-validates), creates the Gitea + release + tag via API with the zip as asset, publishes to the Composer registry, then links the + package to the repo. Uses `RELEASE_TOKEN`. +- Required checks on `main` (`plugin-checks / version-changelog|package|phpunit (pull_request)`) are set + once with `scripts/protect-main.sh` (`tea api`). Build excludes/validation live in + `.config/shopware-extension.yml`. Background: `docs/spec/shopware-guideline-compliance.md`. + ## Adding functionality - New console commands go in `src/Command/`, new scheduled tasks in `src/ScheduledTask/` — both must diff --git a/docs/spec/shopware-guideline-compliance.md b/docs/spec/shopware-guideline-compliance.md index 3603f38..78674a2 100644 --- a/docs/spec/shopware-guideline-compliance.md +++ b/docs/spec/shopware-guideline-compliance.md @@ -10,8 +10,9 @@ on branches `research/shopware-guideline-checklist`, `research/shopware-cli-ci-b - 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. +- 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 @@ -34,7 +35,9 @@ on branches `research/shopware-guideline-checklist`, `research/shopware-cli-ci-b ### 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`: +`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. @@ -51,17 +54,18 @@ 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. +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 to verify while implementing +## 4. Open items (status after the first pipeline run) -- 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). +- 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