From 5569060edb3a3ade0bcf78bc749ea9d83d182592 Mon Sep 17 00:00:00 2001 From: Tsvetan Stoychev Date: Thu, 24 Sep 2026 15:16:59 +0300 Subject: [PATCH] Simplify installation docs and remove obsolete migration guidance --- CHANGELOG.md | 15 +- README.md | 278 +++++++------------------------ docs/PACKAGE-NAMING-MIGRATION.md | 127 -------------- tests/README.md | 98 +++++++++++ 4 files changed, 165 insertions(+), 353 deletions(-) delete mode 100644 docs/PACKAGE-NAMING-MIGRATION.md create mode 100644 tests/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 298fde4..2fcd1de 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,15 +30,8 @@ Notable changes to Basicrum Analytics are recorded here. ### Changed -- **Breaking packaging change:** the Composer name is now - `basicrum/basicrum-magento-2`, retaining the public title "Basicrum Analytics" - and distribution filename `basicrum-magento-2.zip`. No compatibility - replacement is declared. The old-name conflict is omitted during the rename - because VCS imports under the old default-branch name reject it as a self-conflict. - Remove the old package explicitly; Composer does not prevent co-installation. - Magento module/namespace/ACL identifiers and configuration paths are unchanged - by this packaging change. The new Packagist listing uses the same repository; - historical tags are not rewritten. +- The Composer package is `basicrum/basicrum-magento-2`, with the public title + "Basicrum Analytics" and distribution filename `basicrum-magento-2.zip`. - **Breaking:** Magento 2 `p_type` now uses Magento 1's exact 27 named labels for equivalent native pages, including `Checkout Success`, account/address, wishlist, guest-order, and PayPal billing-agreement pages. HTTP 404 takes @@ -78,8 +71,8 @@ Notable changes to Basicrum Analytics are recorded here. - The Admin integration test opens Magento's native Basicrum navigation group before selecting the exact settings link, which is hidden when collapsed. -- Validate rename branches through Composer's validating VCS importer in CI, - including the pre-merge old-name default branch that root validation misses. +- Validate package metadata through Composer's validating VCS importer in CI, + catching import-stage errors that standalone validation misses. - Rebuild the disposable Magento catalog search index before native browser checks, including when retained application/database volumes outlive OpenSearch data. - Fresh disposable Magento provisioning no longer writes the Admin Usage setting diff --git a/README.md b/README.md index 77a431b..1a43e84 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,16 @@ # Basicrum Analytics Basicrum adds Boomerang real user monitoring (RUM) to a Magento 2 storefront. -Monitoring is fail-closed: no Basicrum storefront scripts are emitted unless -the module is enabled and the effective store-scope Beacon Endpoint and UUIDv4 -Brum Site ID are valid. - -## Supported baseline - -The Phase 1 integration baseline is Magento Open Source **2.4.7-p10** with -**PHP 8.3** and Composer 2.10. Platform version requirements are declared in -`tests/integration/baseline.env`; container images are pinned by digest. The full -application dependency set is not locked: first-time provisioning resolves -transitive Composer dependencies, so upstream changes can affect a new install. -Focused PHP checks run on PHP 8.2, -8.3, and 8.4. Composer metadata allows Magento framework 103.x so the module -can be evaluated on adjacent Magento 2.4 release lines, but only the pinned -PHP 8.3 combination is declared for disposable Magento integration testing. -This combination has now been exercised with Luma and built-in full-page cache, -including the installed distribution ZIP. Adobe Commerce, Hyvä, headless/PWA, -Varnish, and other Magento/PHP combinations are **not** certified by that run. -The source repository's `docs/QUALITY-AND-RELEASE-READINESS.md` records the exact -verification scope, skips, and remaining release requirements. +Collect performance data through your Basicrum Beacon Endpoint, with +consent-controlled loading and configurable privacy settings. ## Installation +Run commands from your Magento installation directory as the filesystem owner. +Back up your application and database, and test on staging first. For production, +use your normal deployment process; enable maintenance mode for an in-place +installation and disable it only after successful deployment and verification. + Install Basicrum Analytics from the [`basicrum/basicrum-magento-2`](https://packagist.org/packages/basicrum/basicrum-magento-2) Composer package: @@ -32,40 +19,51 @@ Composer package: composer require 'basicrum/basicrum-magento-2:^0.1' ``` -The version constraint deliberately excludes the historical `0.0.x` releases, -which also appear under the new name when Packagist imports the repository. -Those older versions do not contain the `0.1.0` implementation. -See the [package migration checklist](https://github.com/basicrum/basicrum-magento-2/blob/main/docs/PACKAGE-NAMING-MIGRATION.md) -for the separate maintainer steps and existing-installation considerations. +The version constraint selects the `0.1.x` release line. -For a manual source installation, place this module at the exact path below. -The casing is required on case-sensitive filesystems: +Alternatively, for a manual source installation, place this module at the exact +path below. The casing is required on case-sensitive filesystems: ```text app/code/Basicrum/Analytics ``` -Then enable and initialize the module: +Use either Composer or a manual installation, never both. After either method, +enable and initialize the module: ```sh bin/magento module:enable Basicrum_Analytics bin/magento setup:upgrade bin/magento setup:di:compile -bin/magento cache:flush ``` -Regenerate compiled DI after installation or upgrade, including developer -installations where DI was previously compiled. This applies changed constructor -metadata and the global CSP collector registration. In production mode, deploy -static content using the store's normal deployment process as well. +In production mode, deploy static content for all storefront and Admin locales. +For an English-only installation: + +```sh +bin/magento setup:static-content:deploy en_US +``` + +Replace or extend `en_US` with your actual locales. Then clean caches and verify +that the module is enabled: + +```sh +bin/magento cache:clean +bin/magento module:status Basicrum_Analytics +``` + +Monitoring remains disabled until you configure and enable Basicrum below. + +## Compatibility + +Tested with **Magento Open Source 2.4.7-p10**, **PHP 8.3**, Luma, and built-in +full-page cache. Other Magento/PHP combinations, Adobe Commerce, Hyvä, +headless/PWA storefronts, Varnish, and third-party optimizers are not verified. ## Configuration -Open **Stores > Configuration > Basicrum > Basicrum Analytics**. Every setting supports -Magento default, website, and store inheritance. Display-only status, version, -and callback instructions have no inheritance controls or stored values. -Visitor Consent and Privacy open expanded each time you visit the page. You -can collapse them while working; they reopen on your next visit. +Open **Stores > Configuration > Basicrum > Basicrum Analytics**. Settings support +Magento default, website, and store inheritance. Required settings: @@ -76,10 +74,9 @@ Required settings: is enabled. - **Brum Site ID**: a UUIDv4 copied from the Basicrum backoffice. -If any effective value is disabled, missing, malformed, or unsafe, the -Monitoring Status row explains the inactive state and the storefront template -emits nothing. Values are validated on save and again at render time so -programmatic or stale configuration cannot bypass the runtime gate. +If Basicrum is disabled or required configuration is missing or invalid, no +monitoring scripts are emitted. The Monitoring Status row explains why +monitoring is inactive. Settings are validated on save and at runtime. Collection controls: @@ -96,33 +93,17 @@ Collection controls: dumps put it in `app/etc/env.php`, not shared `app/etc/config.php`. Do not promote development `env.php` values to production. This follows Magento's native [configuration deployment rules](https://experienceleague.adobe.com/en/docs/commerce-operations/configuration-guide/deployment/technical-details). - Existing database values and previously exported files are not rewritten; - review any old shared export of `basicrum/developer/development_mode` before - re-exporting configuration. The default, configuration path, and scope - inheritance are unchanged. - -The runtime emits Magento 1's exact named `p_type` values for equivalent -Magento 2 pages (for example, `Home`, `Product`, `Search`, and -`Checkout Success`), while retaining `p_gen=mage2` and the configured -`brum_site_id`. Unknown actions use `unmapped_`; -an unavailable action uses `unknown`. The [page-type alignment notes](docs/PAGE-TYPE-ALIGNMENT.md) -list all mappings, native-route adaptations, and reporting impact. -Boomerang uses `instrument_xhr=false`, -Continuity and ResourceTiming with `splitAtPath`, and Secure/SameSite Strict -cookie settings, matching the reviewed Basicrum configuration. - -When the effective runtime configuration is active, the module adds only the -normalized Beacon Endpoint origin (scheme, host, and optional port) to the -storefront `connect-src` and `img-src` CSP policies. Paths and query strings -are not copied into CSP. Inactive or invalid configuration adds no collector -origin. This covers Boomerang's send-beacon/XHR and image-fallback transports; -it does not weaken other directives or add a wildcard. + +Beacons include the configured `brum_site_id`, `p_gen=mage2`, and a `p_type` +page label such as `Home`, `Product`, `Search`, or `Checkout Success`. +Unmapped actions use `unmapped_`; an unavailable +action uses `unknown`. ## Consent integration -Phase 1 provides a manual, page-level callback contract. Basicrum does not -display a banner, decide whether consent is legally required, infer consent -from a cookie or legacy mode string, or persist its own consent decision. +Basicrum provides manual, page-level callbacks for your consent platform. +It does not display a banner, automatically connect to consent providers, +infer consent from cookies, or persist its own consent decision. When the site's external consent tool authoritatively allows performance monitoring on the current page, call: @@ -156,51 +137,7 @@ state. The callbacks are registered by the footer loader; calls made before registration are not queued. Connect both allow and deny/change events in the site's consent tool on every page. -Automatic consent-provider adapters are not part of Phase 1. - -## Upgrade behavior from 0.0.2 - -No data migration renames, deletes, or heuristically rewrites stored settings. -Review the following before enabling the upgraded module: - -- The Composer package name changes from `basicrum/basicrum-analytics` to - `basicrum/basicrum-magento-2`. The two packages must not be installed together; - Composer does not prevent that combination during the naming transition. - Remove the old requirement and check the resolved lock file for old-name - transitive dependencies when the new release is available; this is not an - automatic or backward-compatible replacement. A manual `app/code` copy must not coexist - with a Composer installation either. No stored configuration is deleted. - -- Magento 2 `p_type` labels now match Magento 1, including capitalization and - spaces. This intentionally changes existing report groupings; historical - beacons are not migrated and no legacy-label mode is provided. Update any - report filters and purge cached HTML after upgrading. WordPress and Magento - 1 labels are unchanged. - -- Before the first public release, the technical module identifier and PHP - namespace were normalized to the “Basicrum” spelling. This is an intentional - breaking rename; the supported identifiers are `Basicrum_Analytics` and - `Basicrum\\Analytics`. Lowercase `basicrum/*` configuration paths are - unchanged. The exact manual installation path is documented above. - -- Existing `basicrum/general/beacon_endpoint` values remain in place but now - receive save-time and runtime validation. Invalid values make monitoring - inactive. HTTP becomes HTTPS unless the development exception is explicit. -- `basicrum/general/brum_site_id` is new and required. Existing enabled stores - stay inactive until a valid UUIDv4 value is configured at the appropriate - scope. -- Existing `basicrum/consent/enabled=0` means deliberate immediate loading. - Value `1` means consent-controlled loading. Invalid or absent effective - values fail to consent-controlled behavior. -- The obsolete `basicrum/consent/mode` selector and runtime handling are - removed. Existing database rows are left untouched but ignored, including - `manual`, `explicit`, `implicit`, `cookie`, and `gdpr`. Only the consent-required - switch controls loading; none of these old strings counts as consent. Manual - callbacks remain the supported integration. -- The old five-second wait was hardcoded and had no stored setting. It is - replaced with `basicrum/performance/wait_after_onload` and `delay_ms`, both - defaulting to off/zero. Administrators who need the former timing must - explicitly enable it and enter 5000 ms. +## Caching and CSP After changing module configuration, clean Magento configuration, layout, block HTML, and full-page caches. Production deployments must also publish the @@ -208,104 +145,16 @@ new static assets and invalidate any CDN or optimizer cache that can retain old HTML or JavaScript. Magento's versioned static asset URLs provide browser cache invalidation only after the deployment/content version changes. -The template uses Magento's `SecureHtmlRenderer`, the loader and Boomerang -assets are same-origin module assets, and the validated collector origin is -added dynamically to storefront CSP. The disposable-store check exercises the -actual layout and CSP path, but Phase 1 does not claim compatibility with a -broad set of third-party script delay/combine/optimizer extensions. +The loader and Boomerang are first-party Magento static assets. Inline scripts +use Magento's `SecureHtmlRenderer` for CSP-compatible rendering. -## Testing - -Fast checks: - -```sh -docker run --rm -v "$PWD:/module:ro" -w /module php:8.3-cli php tests/php/run.php -npm ci -npm test -``` - -The fast PHP harness uses test doubles to cover defaults, validation, save -normalization, runtime gates, scope inheritance, CSP origin policy, all Magento 1-aligned page-type mappings -and fallbacks, template -serialization/loader selection, and artifact provenance. Browser tests execute -the packaged readable and minified loaders and the real bundled Boomerang -against intercepted local requests. Global setup renders the actual PHP footer -template using PHP 8.3 in Docker (Docker must be running), then the browser -executes its inline configuration and Wait After Onload plugin. Set -`BASICRUM_TEST_PHP=php` (or an absolute executable path) to use an installed -PHP CLI instead. The Chromium CI job explicitly provisions PHP 8.3 and selects -it through this setting; fixture rendering does not pull or start a Docker image -in that job. A missing or failing selected PHP executable fails setup without -falling back to Docker. -Magento block/renderer doubles are used here; native rendering is covered by -the separate integration suite. The checks cover pre-consent silence, one-time -loading, denial and withdrawal races, cookie cleanup, query redaction, and -beacon identity, delayed sending, and cancellation of the rendered wait timer. - -For the actual layout/template/static-content/CSP/storefront-to-beacon path, -use the guarded disposable-store harness in `tests/integration/README.md`. -It also exercises Magento's real Admin configuration-save model, backend -validation, and default/website/store inheritance inside rolled-back database -transactions. Browser traffic is limited to the disposable storefront/Admin; -the expected beacon is fulfilled locally and unexpected destinations fail the -test. External payment scripts must be disabled in that test installation. -The native suite also renders a test-only, non-cacheable Magento page under -enforcing CSP with inline scripts disabled. It checks matching bootstrap -nonces, real first-party script execution and consent-gated beacons, and a -blocked unnonced inline negative control. The fixture is never packaged with -the extension. This is separate from the report-only homepage FPC checks; it -does not certify nonce handling on cacheable pages or custom strict-dynamic -policies. See the integration README for fixture installation and scope. -The regular CI workflow runs strict Composer 2.10 validation, a validating VCS -import regression before and after the default-branch rename, and optimized -production classmap checks plus the fast PHP and Chromium checks. The VCS test -uses the real Composer importer on a temporary local Git repository containing -the candidate metadata and a synthetic historical tag; it needs no network or -Packagist account. Run it with: - -```sh -docker run --rm --network none -v "$PWD:/app:ro" -w /app composer:2.10 php tests/php/check-composer-import.php /usr/bin/composer -``` - -This is not a live Packagist update or a Magento Composer installation. The Chromium -job uploads an HTML report with traces from failed test attempts, retained for -seven days. A flaky pass still fails the job; retries do not hide failures. -Additional CI checks run Magento-aware PHPStan level 8 and Magento coding -standards against real Magento components, with lowest/stable dependency -resolution on PHP 8.2–8.4 and a locked PHP 8.3 job. These component checks are -not full-platform compatibility certification. The committed tooling lock requires -PHP 8.3 or 8.4 and resolves framework 103.0.9 (the Magento 2.4.9 component line). -The locally tested PHP 8.3 lowest resolution uses framework 103.0.7 (2.4.7 GA), -not 2.4.7-p10. CI's lowest/stable jobs resolve afresh for their PHP version; their -logs report the exact component versions. No PHPStan run against the native -2.4.7-p10 dependency set is claimed. Run the locked tools locally on PHP 8.3/8.4: - -```sh -composer --working-dir=tests/quality install --no-interaction --no-scripts -sh tests/quality/check.sh -``` +When monitoring configuration is active and valid, Basicrum adds the Beacon +Endpoint origin (scheme, host, and optional port) to storefront `connect-src` +and `img-src` CSP policies. Paths and query strings are excluded. Disabled or +invalid configuration adds no collector origin. No wildcard is added. -The native CI workflow provisions a separate Magento-version/image-pinned stack from the -anonymous Mage-OS mirror; it does not use production credentials. It disables -external Braintree scripts only in that test stack. See the integration README -for setup, synthetic credentials, localhost-only ports, and cleanup. -Before tagging Phase 1 as `0.1.0`, the documented native -release gate is also required: it requires a clean candidate checkout, verifies -the distribution ZIP and registered installed module match it, and enforces all versions in `baseline.env`, -then runs Magento upgrade, DI compilation, static deployment, native save tests, -storefront/beacon assertions with a proven full-page-cache HIT, and an authenticated -Admin rendering check. A temporary challenge binds the browser URL to that -installation and its web PHP version; served loader/Boomerang bytes must match -the candidate. A visitor with measurement cookies populates a fresh cache entry; -another visitor's first request to that URL must be a HIT and remain silent until -its own allow callback. It rechecks candidate identity afterward and records the -tested commit SHA in its success output. Run `npm ci` first: the native runner -uses only the installed Playwright binary, never an automatic download. -The production archive is built from the clean Git commit, never loose working-tree -files. It excludes tests, CI, developer tooling/configuration and generated output, -and retains production code/assets and license notices. Installed-package checks -reject all extra files, including leftover development directories and hidden files. -No remote CI job is reported as passing merely because its definition was added. +If your store uses script delay, combination, or other optimization extensions, +verify consent handling and script loading on staging before deployment. ## Privacy and lifecycle notes @@ -318,17 +167,16 @@ wrapper is present so the external tool can signal that decision. Immediate mode has no such gate. Disabling the module and cleaning page caches stops future script emission. -Uninstall behavior and settings deletion are not automated in Phase 1; removing -module files does not delete configuration or data already sent to a collector. +Removing module files does not delete stored configuration or data already +sent to a collector. Store operators remain responsible for their consent tool, privacy disclosure, collector access, retention, and deletion processes. ## Third-party software and license -The reviewed Boomerang 1.815.60 artifact and loader provenance, checksum, and -BSD license are recorded in `THIRD-PARTY-NOTICES.txt` and -`view/frontend/web/js/boomr/LICENSE.txt`. +Boomerang 1.815.60 provenance, checksums, and license notices are recorded in +[Third-party notices](THIRD-PARTY-NOTICES.txt) and the +[Boomerang license](view/frontend/web/js/boomr/LICENSE.txt). -The module is licensed under the [MIT License](LICENSE), matching its existing -Composer declaration. The root license does not replace the bundled Boomerang -BSD license or other third-party notices. +Basicrum Analytics is licensed under the [MIT License](LICENSE). Bundled +Boomerang remains covered by its BSD license and third-party notices. diff --git a/docs/PACKAGE-NAMING-MIGRATION.md b/docs/PACKAGE-NAMING-MIGRATION.md deleted file mode 100644 index 4a04ec2..0000000 --- a/docs/PACKAGE-NAMING-MIGRATION.md +++ /dev/null @@ -1,127 +0,0 @@ -# Composer and Packagist naming migration - -## Scope and identity - -The package identity is now `basicrum/basicrum-magento-2`. The naming change -was merged and the new Packagist listing was registered on 2026-09-23. -Packagist imported `dev-main` and historical tags successfully. Registration -preceded `0.1.0` publication at the owner's request; until that tag is published, -the latest stable version on the new listing is still the old `0.0.2` code. -Publication and abandonment are separate maintainer actions, not effects of -changing `composer.json`. - -| Surface | Canonical value | -| --- | --- | -| Composer / Packagist | `basicrum/basicrum-magento-2` | -| Public title and Admin section | Basicrum Analytics | -| Description | Basicrum real user monitoring (RUM) for Magento 2 | -| Distribution ZIP | `basicrum-magento-2.zip` | -| Magento module (unchanged) | `Basicrum_Analytics` | -| PHP namespace (unchanged) | `Basicrum\Analytics` | -| Configuration paths (unchanged) | `basicrum/*` | - -The ACL resource, layout aliases, JavaScript identifiers, Beacon Endpoint and -Brum Site ID names also stay unchanged. Historical tags, the existing MIT -declaration and third-party notices are preserved. - -## Composer decision - -The rename does not declare a conflict with `basicrum/basicrum-analytics`. -Before the naming change was merged, `main` still used that old name, and -Composer's VCS importer assigned it to the rename branch too. An old-name -conflict then became a self-conflict and Packagist rejected the branch, -even though standalone `composer validate` passed. -The initial PR declared that conflict; the Packagist update failure exposed this -import-stage gap. CI now exercises Composer's validating VCS importer with both -old-name and new-name default branches, the real candidate metadata, and a -synthetic historical tag in a disposable local Git repository. - -Both packages must not be installed together, but **Composer does not enforce -that restriction during this transition**. Remove the old requirement explicitly -and inspect the resolved lock file for transitive old-name dependencies. -Any later conflict declaration requires a separately verified migration step, -including successful imports for the affected Packagist listings; it is not -automatically safe merely because this PR was merged. There is no `replace`, `provide`, -compatibility metapackage, class alias or automatic upgrade: this is an -intentional package-name break, not a promise to satisfy old dependencies. -Composer cannot detect a duplicate manually installed `app/code` copy. - -Package names come from the default branch during VCS import. Composer can -therefore expose historical tags under the new name without changing those -tags. An unversioned `composer require` could select the old `0.0.2` code before -the new release exists. The README uses `basicrum/basicrum-magento-2:^0.1` -so that installation requires the new release rather than an old imported tag. -Do not present `dev-main` or an imported `0.0.x` tag as the new stable release. - -## Maintainer checklist - -1. Merge the naming change into the repository's default branch, `main`. - A feature branch alone does not establish the new Packagist identity. - After the corrected branch is pushed, verify that the old listing's next - update no longer rejects it for a self-conflict. If the hook has not retried, - an authorized maintainer can trigger an update. Repeat the import check after - merging; a local test does not certify the hosted updater's state. -2. The owner approved the root MIT LICENSE and its 2025–2026 Tsvetan Stoychev - copyright line for `0.1.0`. Run the release gate against the exact clean - commit to be tagged; CI success alone is not release certification. Keep the - Composer `version` field absent. Do not move, delete or reuse `0.0.1` or `0.0.2`. -3. Publish the approved new `0.1.0` tag as a separate release action. For a future - rename, publish the intended stable release before submitting the new listing: - Packagist's generated install command has no version constraint and can - otherwise select old code. This listing was registered first at the owner's - request; verify that `0.1.0` supersedes `0.0.2` before abandoning the old name. -4. As an authorized `basicrum` maintainer, submit the same repository URL to - Packagist under `basicrum/basicrum-magento-2`. Configure/verify its GitHub - update hook and trigger an update if needed. Do not assume updating the old - listing renames it. Verify `0.1.0` is the newest stable version, with the - intended source commit, description, support links and README. - Inspect imported historical versions; their appearance is not evidence that - `0.0.x` contains the new implementation. Verify a clean disposable Magento - Composer install using `^0.1`, including `Basicrum_Analytics` registration. -5. Once the new stable package is available and verified, mark - `basicrum/basicrum-analytics` abandoned in the **old listing's Packagist UI**, - with `basicrum/basicrum-magento-2` as the suggested alternative. Do not add an - `abandoned` field to the renamed package's `composer.json`. Keep the old - listing and historical versions; do not delete them or expect download - statistics to transfer. Abandonment is a notice, not a lock-file migration. - -## Existing development installations - -After the new release is available, review the project's dependency graph and -change the old requirement explicitly. For a project that directly requires -the old package, the intended Composer transaction is: - -```sh -composer remove basicrum/basicrum-analytics --no-update -composer require 'basicrum/basicrum-magento-2:^0.1' -``` - -Back up and review the resulting `composer.json` / `composer.lock` diff. If a -different package still requires the old name, stop and update that dependency -deliberately. Do not deploy a lock file containing both names; there is no -solver-level conflict guard in this rename. This transaction only changes Composer -packages. It does not migrate the historical module-name capitalization, -Magento's enabled-module configuration, or third-party customizations. Review -the README's upgrade notes and Magento deployment steps. Remove any duplicate -manual installation through the project's normal deployment process, preserve -stored settings, and rebuild compiled DI/static assets and caches as documented. - -## Review and sources - -CLI consultations used `grok-4.7` at high reasoning effort (reported -`grok-4.7-build`) and `claude-opus-5-5` at maximum effort. Both initially recommended an explicit -conflict without `replace` / `provide`. We removed that conflict -after the Packagist failure and a local reproduction using Composer's validating -VCS importer; the no-alias decision remains. Opus also identified the old-tag install trap -and recommended publishing the new stable tag before submitting the listing. -An initial Grok claim that old tags stay confined to the old name was corrected -against Composer source. A fixed `support.source` URL is deliberately omitted: -Composer's GitHub driver supplies a version-specific source link instead. -Tests guard package identity and dependency semantics; the native Admin test -opens Magento's native collapsible navigation before checking the exact rendered -section name and logo caption rather than adding a repository-wide branding scan. - -- [Packagist maintainer rename procedure](https://github.com/composer/packagist/issues/47) -- [Composer conflict semantics](https://getcomposer.org/doc/04-schema.md#conflict) -- [Composer VCS name normalization, including historical tags](https://github.com/composer/composer/blob/2.10.3/src/Composer/Repository/VcsRepository.php#L432-L438) -- [Packagist publication and update hooks](https://packagist.org/about) diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..a760015 --- /dev/null +++ b/tests/README.md @@ -0,0 +1,98 @@ +# Development checks + +These instructions are for maintainers working from a source checkout, not for +installing Basicrum on a store. Run commands from the repository root. Browser +checks require Node.js 20 or newer; the default PHP fixture setup uses Docker. +See [native Magento integration](integration/README.md) for the disposable +installation and release gate. + +Fast checks: + +```sh +docker run --rm -v "$PWD:/module:ro" -w /module php:8.3-cli php tests/php/run.php +npm ci +npm test +``` + +The fast PHP harness uses test doubles to cover defaults, validation, save +normalization, runtime gates, scope inheritance, CSP origin policy, all Magento +1-aligned page-type mappings and fallbacks, template serialization/loader +selection, and artifact provenance. Browser tests execute +the packaged readable and minified loaders and the real bundled Boomerang +against intercepted local requests. Global setup renders the actual PHP footer +template using PHP 8.3 in Docker (Docker must be running), then the browser +executes its inline configuration and Wait After Onload plugin. Set +`BASICRUM_TEST_PHP=php` (or an absolute executable path) to use an installed +PHP CLI instead. The Chromium CI job explicitly provisions PHP 8.3 and selects +it through this setting; fixture rendering does not pull or start a Docker image +in that job. A missing or failing selected PHP executable fails setup without +falling back to Docker. +Magento block/renderer doubles are used here; native rendering is covered by +the separate integration suite. The checks cover pre-consent silence, one-time +loading, denial and withdrawal races, cookie cleanup, query redaction, and +beacon identity, delayed sending, and cancellation of the rendered wait timer. + +For the actual layout/template/static-content/CSP/storefront-to-beacon path, +use the guarded disposable-store harness in `tests/integration/README.md`. +It also exercises Magento's real Admin configuration-save model, backend +validation, and default/website/store inheritance inside rolled-back database +transactions. Browser traffic is limited to the disposable storefront/Admin; +the expected beacon is fulfilled locally and unexpected destinations fail the +test. External payment scripts must be disabled in that test installation. +The native suite also renders a test-only, non-cacheable Magento page under +enforcing CSP with inline scripts disabled. It checks matching bootstrap +nonces, real first-party script execution and consent-gated beacons, and a +blocked unnonced inline negative control. The fixture is never packaged with +the extension. This is separate from the report-only homepage FPC checks; it +does not certify nonce handling on cacheable pages or custom strict-dynamic +policies. See the integration README for fixture installation and scope. +The regular CI workflow runs strict Composer 2.10 validation, validating VCS +import regression checks, and optimized production classmap checks plus the +fast PHP and Chromium checks. The VCS test uses the real Composer importer on +a temporary local Git repository containing +the candidate metadata and a synthetic historical tag; it needs no network or +Packagist account. Run it with: + +```sh +docker run --rm --network none -v "$PWD:/app:ro" -w /app composer:2.10 php tests/php/check-composer-import.php /usr/bin/composer +``` + +This is not a live Packagist update or a Magento Composer installation. The Chromium +job uploads an HTML report with traces from failed test attempts, retained for +seven days. A flaky pass still fails the job; retries do not hide failures. +Additional CI checks run Magento-aware PHPStan level 8 and Magento coding +standards against real Magento components, with lowest/stable dependency +resolution on PHP 8.2–8.4 and a locked PHP 8.3 job. These component checks are +not full-platform compatibility certification. The committed tooling lock requires +PHP 8.3 or 8.4 and resolves framework 103.0.9 (the Magento 2.4.9 component line). +The locally tested PHP 8.3 lowest resolution uses framework 103.0.7 (2.4.7 GA), +not 2.4.7-p10. CI's lowest/stable jobs resolve afresh for their PHP version; their +logs report the exact component versions. No PHPStan run against the native +2.4.7-p10 dependency set is claimed. Run the locked tools locally on PHP 8.3/8.4: + +```sh +composer --working-dir=tests/quality install --no-interaction --no-scripts +sh tests/quality/check.sh +``` + +The native CI workflow provisions a separate Magento-version/image-pinned stack from the +anonymous Mage-OS mirror; it does not use production credentials. It disables +external Braintree scripts only in that test stack. See the integration README +for setup, synthetic credentials, localhost-only ports, and cleanup. +Before publishing a release, run the documented native release gate against +the exact candidate commit. It requires a clean candidate checkout, verifies +the distribution ZIP and registered installed module match it, and enforces all versions in `baseline.env`, +then runs Magento upgrade, DI compilation, static deployment, native save tests, +storefront/beacon assertions with a proven full-page-cache HIT, and an authenticated +Admin rendering check. A temporary challenge binds the browser URL to that +installation and its web PHP version; served loader/Boomerang bytes must match +the candidate. A visitor with measurement cookies populates a fresh cache entry; +another visitor's first request to that URL must be a HIT and remain silent until +its own allow callback. It rechecks candidate identity afterward and records the +tested commit SHA in its success output. Run `npm ci` first: the native runner +uses only the installed Playwright binary, never an automatic download. +The production archive is built from the clean Git commit, never loose working-tree +files. It excludes tests, CI, developer tooling/configuration and generated output, +and retains production code/assets and license notices. Installed-package checks +reject all extra files, including leftover development directories and hidden files. +No remote CI job is reported as passing merely because its definition was added.