Skip to content

checklist.md

Latest commit

 

History

History
186 lines (147 loc) · 8.45 KB

checklist.md

File metadata and controls

186 lines (147 loc) · 8.45 KB
Raw

Basicrum Plugin Quality Checklist

Work through these items in order. An item is complete only when its implementation, tests, and documentation requirements are all satisfied.

1. Preserve beacon URLs in generated JavaScript

  • Replace the display-context esc_url() call in Assets::build_config_js() with URL sanitization appropriate for JavaScript serialization.
  • Add a regression test using a beacon URL with multiple query parameters.
  • Verify the generated JavaScript contains the original & separators and does not contain HTML entities such as &.
  • Run PHP lint, PHPCS, and unit tests.

Acceptance criteria:

  • Beacon URLs with query strings reach Boomerang unchanged and remain safely encoded through wp_json_encode().

2. Resolve the unused consent mode setting

  • Define the intended behavior for explicit, implicit, and cookie_popup modes.
  • Decide whether each mode has distinct runtime behavior.
  • Implement the defined behavior, or remove modes that do not represent real behavior and keep a single consent-enabled switch.
  • Keep defaults, settings UI, validation, runtime behavior, documentation, and translations synchronized.
  • Add PHP tests for every supported setting and loader selection path.

Decision:

  • Immediate loading and consent-controlled loading are the only observable policies. The unused explicit, implicit, and cookie_popup development values were removed before the first public release.
  • Basicrum supplies an integration gate, not a consent popup, legal-basis decision, or compliance guarantee.
  • In consent-controlled loading, the site's external consent tool is the source of truth on every page. Automatic handling loads one unambiguous supported adapter after the consent loader; manual handling leaves adapter placement to the webmaster. The adapter calls exactly one of the two public callbacks. Basicrum does not persist consent across page loads.
  • The settings page uses progressive disclosure: automatic handling shows only a compact verdict, provider evidence, one next action, and copyable non-secret diagnostics. Manual handling reveals the callback contract and copyable provider adapters in a separate sibling panel. Blocked automatic states can reveal the appropriate manual setup but never save the mode automatically.

Acceptance criteria:

  • Every consent option shown to an administrator has observable and documented runtime behavior.
  • No unused consent settings remain in stored options or the UI.

3. Add JavaScript consent and loader tests

  • Add a JavaScript test runner and a documented test command.
  • Test that Boomerang does not load before consent is granted.
  • Test that opt-in loads Boomerang exactly once.
  • Test that repeated opt-in calls do not load duplicate scripts.
  • Test that opt-out disables Boomerang when it is already loaded.
  • Test removal of Boomerang RT and BA cookies during opt-out.
  • Test measurement-cookie cleanup for the current host and parent domains.
  • Run the same behavioral assertions against minified and unminified loaders.
  • Test the Borlabs Cookie 3.0.6+ adapter contract.
  • Test the shared WP Consent API adapter for opt-in and opt-out regions.
  • Test the connected CookieYes fallback with its documented update payload.
  • Add JavaScript tests to CI.

Acceptance criteria:

  • Privacy-critical loader behavior is covered independently of PHP tests.
  • Minified and unminified loaders pass the same behavior suite.

4. Make installation and release artifacts resilient

  • Handle a missing vendor/autoload.php without an uncaught PHP fatal error.
  • Provide a clear administrator-facing error or use a plugin-owned autoloading strategy that does not require a generated vendor directory.
  • Move release packaging into one reusable script used by local builds and CI.
  • Build the exact release ZIP during CI.
  • Inspect the ZIP for required runtime files and excluded development files.
  • Install the ZIP into a clean WordPress instance.
  • Activate the packaged plugin through WP-CLI.
  • Render an admin request and a frontend request after activation.
  • Verify the frontend contains the expected loader when the plugin is enabled.
  • Generate and publish a SHA-256 checksum for release artifacts.

Acceptance criteria:

  • The generated ZIP, rather than the source checkout, installs, activates, and serves requests without warnings or fatal errors.

5. Expand the compatibility matrix

  • Keep the minimum combination: PHP 7.4 and WordPress 6.0.
  • Add the latest stable WordPress release as an explicit integration target.
  • Keep WordPress trunk as an allowed early-warning target.
  • Add PHP 8.0 so the declared >=7.4 range has no untested gap.
  • Add PHP 8.4 and PHP 8.5 unit coverage.
  • Test the latest stable WordPress release with a currently supported PHP version.
  • Test WordPress trunk with the newest compatible PHP version in the first CI run of the expanded matrix.
  • Add an isolated WooCommerce E2E suite covering shop, product, cart, checkout, order-pay, and order-received page types through actual Basicrum beacons.
  • Update Tested up to only after the stable integration test passes.
  • Document how compatibility metadata is updated for each release.

Current compatibility reference:

Acceptance criteria:

  • CI passes the minimum, latest stable, and forward-looking runtime boundaries represented by the plugin metadata.

6. Add stronger automated analysis and dependency controls

  • Add PHPStan with WordPress stubs and select an initial enforced level.
  • Add composer validate --strict to CI.
  • Add composer audit --locked to CI.
  • Configure dependency update automation for Composer and GitHub Actions.
  • Set explicit minimal GITHUB_TOKEN permissions in every workflow.
  • Give release workflows only the additional permissions required to upload assets.
  • Pin third-party GitHub Actions to immutable commit SHAs.
  • Document how pinned actions are reviewed and updated.

Acceptance criteria:

  • Type issues, invalid package metadata, known dependency advisories, and excessive workflow permissions are checked automatically.

7. Make JavaScript and translation artifacts reproducible

  • Add a documented JavaScript build command.
  • Generate minified standard and consent loaders from their unminified sources.
  • Record the minifier and its version in a lock file.
  • Make CI regenerate the loaders and fail when the committed output differs.
  • Document the source and version of the bundled Boomerang asset.
  • Add a repeatable command for generating languages/basicrum.pot.
  • Keep locale-specific PO and MO files out of the repository and release ZIP.
  • Keep POT generation as a local maintenance command; the standalone translation CI job was removed by product decision.

Acceptance criteria:

  • A clean checkout can reproduce all committed minified and translation assets without manual editing.

8. Enforce repository conventions in CI

  • Add an automated check that rejects en dash and em dash characters in tracked source, comments, documentation, and user-facing text.
  • Add a version consistency check covering the plugin header, BASICRUM_VERSION, Stable tag, changelog, and release tag.
  • Run both checks in pull requests and pushes to the main branch.
  • Document the checks in AGENTS.md and the contributor documentation.

Acceptance criteria:

  • Repository conventions and version metadata cannot drift silently even when changes are made without an agent.

Final release gate

  • PHP syntax lint passes.
  • PHPCS passes.
  • PHP unit tests pass across the supported PHP matrix.
  • WordPress integration tests pass across the supported WordPress matrix.
  • JavaScript tests pass.
  • Static analysis passes.
  • Composer validation and audit pass.
  • Generated asset checks pass.
  • The packaged ZIP smoke test passes.
  • Version and repository convention checks pass.