Prepare plugin for WordPress.org submission

Author: Tsvetan Stoychev

docs/audits/wporg-submission-checklist.md

@@ -0,0 +1,132 @@
+# WordPress.org Submission Checklist (2026-07-19)
+
+Factuality and ambiguity audit of the submission surfaces (readme.txt,
+basicrum.php header, wordpress-org-assets, release ZIP) at version 0.0.8,
+ahead of the plugin-directory submission. Method: four auditors (line-by-line
+readme factuality vs code, current wp.org handbook requirements, two-persona
+ambiguity sweep, hands-on official readme validator + reviewer-style ZIP
+inspection); every non-clean verdict adversarially re-checked by two
+refuters. 84 claims audited: 52 clean, 24 upheld findings, 8 overturned.
+
+## 1. Blockers - must be resolved before submission
+
+- [x] RESOLVED 2026-07-20: user registered the wordpress.org account `basicrum`; readme.txt Contributors updated to `basicrum`. Original finding: Contributors username did not exist. The OFFICIAL wp.org readme
+  validator returned verbatim: "The following contributors listed were
+  ignored, as the WordPress.org user could not be found. tstoychev."
+  Register the wordpress.org account with exactly that username (or change
+  readme.txt line 2 to the registered account that will submit), and
+  confirm profiles.wordpress.org/tstoychev resolves. (D1a, R02, B6)
+- [x] RESOLVED 2026-07-20: Boomerang BSD LICENSE.txt now ships at assets/js/boomr/LICENSE.txt; readme.txt Third-party section and THIRD-PARTY-NOTICES.txt name the source commit and repositories. UPGRADED 2026-07-20: build reproduced BYTE-IDENTICAL (SHA-256 90e8a1c8...) from basicrum/boomerang master commit ead2783a with Node 12 + npm ci + grunt clean build --build-flavor=cutting-edge --build-number=815; the in-file banner stamps parent commit 564759ed because the final continuity.js change was uncommitted at original build time - docs now state both hashes; tools/verify-boomerang-provenance.sh guards bundle/docs sync via make conventions. Original finding: human-readable source for the bundled Boomerang (guideline 4:
+  reviewers require public, maintained access to source and build tools
+  for minified files). assets/js/boomr/ ships only the .min.js; its header
+  says "See the accompanying LICENSE.txt" and none accompanies it. Add to
+  readme.txt (Development or Third-party section) and THIRD-PARTY-NOTICES.txt:
+  the upstream repository, the exact source commit (the bundle header
+  carries 564759ed70de7801bb64de5e2025fb6ac049ff5f), and the build
+  procedure; ship Boomerang's BSD license text alongside the bundle. (B2)
+- [x] RESOLVED 2026-07-20: phpstan.neon.dist added to .distignore and the verify-release dev-file regex; ZIP rebuilt and verified clean. Original finding: dev file leaks into the ZIP: release/basicrum.zip contains
+  basicrum/phpstan.neon.dist. Add it to plugins/basicrum/.distignore and
+  to the verify-release.sh dev-file regex, rebuild. Plugin Check would
+  flag it. (D2a, B7)
+
+## 2. Reviewer-flag items - fix to avoid review friction
+
+- [x] RESOLVED 2026-07-20: External services section added to readme.txt. Original: add an "External services" readme section in the current
+  reviewer-requested format: name the service (operator-configured
+  collector; basicrum.com hosted option), what data is sent and when
+  (performance beacons: URLs, timings, page type, site id; IP and user
+  agent visible to the collector), and links to the service terms/privacy
+  pages. The FAQ covers parts of this but not in the expected form. (B4)
+- [x] RESOLVED 2026-07-20: "Does Basicrum set cookies?" FAQ added (RT named with attributes and lifetime; BA described as legacy removal); RT also named in the Privacy Policy Guide text (Privacy.php) with test assertions. Original: add a cookies FAQ: the readme never names the first-party RT and BA
+  cookies the listing's own privacy story depends on ("Does Basicrum set
+  cookies?" - names, purpose, consent-mode behavior, opt-out removal).
+  (C10)
+- [x] RESOLVED 2026-07-20: changelog collapsed to a single first-release entry. Original: collapse the 0.0.8 changelog into a single first-release feature
+  entry; the current six bullets describe diffs against never-published
+  0.0.x builds and can be misread as shipped-version history. Decide
+  whether 0.0.7/0.0.6 entries stay (internal history) or fold in. (C13,
+  C14)
+- [ ] Run Plugin Check against the BUILT release/basicrum.zip (not the
+  repo tree) after the fixes and keep the output for the submission. (B7)
+- [ ] Tested up to 7.0: internally defensible (blocking CI rows for wp
+  7.0 exist; format correct - verdict overturned by refuters), but
+  re-confirm on submission day that WordPress 7.0 is the current released
+  stable. (R05)
+
+## 3. Ambiguity fixes - upheld copy issues
+
+- [x] RESOLVED 2026-07-20: FAQ reworded (hosted account is one way; self-hosted needs no account). Original: account FAQ answered "Yes." then contradicts
+  itself: self-hosted collectors need no account. Reword: collector
+  endpoint + Brum Site ID required; hosted account is one way to get
+  them. (R24, C04)
+- [ ] Vocabulary bridge: the compliance FAQ says "immediate and
+  consent-controlled loading" while the settings radios say "Monitor
+  without consent" / "Require consent before monitoring". Bridge both
+  vocabularies once, then use the radio labels. (C02)
+- [ ] Define the server-side nouns once: collector (receives beacons) vs
+  backoffice (dashboard where the Brum Site ID lives) vs account (hosted
+  option); "backoffice" is currently undefined jargon. (C15)
+- [ ] Disambiguate "Basicrum" = plugin vs company vs service in the
+  query-string FAQ: data goes only to the operator-configured Beacon URL;
+  the plugin makes no requests to basicrum.com. (C16)
+- [ ] HTTP Strictness FAQ still inverts the semantics (enabling
+  "Strictness" relaxes enforcement). Rewrite the FAQ to lead with the
+  default (auto-upgrade to HTTPS) and what the toggle actually allows;
+  the label rename remains open from the operator-experience audit. (C08)
+- [ ] "eligible pages" in the contributed privacy-policy text
+  (Privacy.php immediate-mode sentence) is undefined for site owners;
+  spell out: frontend pages, admins excluded unless Track Admin Users.
+  (C12)
+- [ ] Define "connected" CookieYes at first use (linked to the CookieYes
+  web app so its browser consent API is present). (C07)
+- [ ] Replace "fails closed" jargon: "keeps monitoring switched off until
+  its consent API reports a decision". (C19)
+- [ ] "How it works" step 2 orders enable-before-Site-ID, contradicting
+  Installation steps 4-5 and triggering the enabled-but-inactive notice;
+  align the order. (C22)
+- [ ] "after the configured Script Position" forward-references an
+  undefined setting; name it: Basicrum > Performance > Script Position
+  (header or footer). (C23)
+
+## 4. Optional but recommended
+
+- [ ] Screenshots: the section was correctly removed (no files existed),
+  but an image-free listing forces users to imagine the settings-driven
+  consent workflow. Capture screenshot-1..N.png using the exact current
+  labels (Visitor Consent, Consent Tool Connection) and restore a
+  matching section. (C24)
+- [ ] Spot-check the two basicrum.com URLs (home, /contact/) resolve;
+  reviewers click them. (R45)
+- [ ] CookieYes "modern ... runtime" - one refuter pair split on this;
+  consider "CookieYes 3.x" with a one-line legacy note for precision.
+  (C06)
+
+## 5. Verified clean (highlights)
+
+- [x] Version consistency: header, BASICRUM_VERSION, Stable tag, top
+  changelog all 0.0.8; no git tags, consistent with first release. (R07)
+- [x] Short description 95 chars (under 150), byte-identical to the
+  header Description; privacy-first claim backed by defaults. (R09, C01
+  overturned)
+- [x] MIT license declared consistently (readme, header, LICENSE.md,
+  composer.json); GPL-compatible; Boomerang BSD is GPL-compatible;
+  THIRD-PARTY-NOTICES.txt scopes correctly. (R08, B1)
+- [x] All five tags valid and implemented; Requires at least 6.0 and
+  Requires PHP 7.4 match headers, composer, and CI matrix. (R03, R04, R06)
+- [x] Feature claims verified against code: page-type values verbatim in
+  PageTypeDetector.php with correctly hedged non-exhaustive lists;
+  detection markers and version floors match ConsentIntegration.php;
+  cache-plugin list matches Compatibility.php; guideline 7 satisfied
+  (off by default, consent-controlled default). (R12-R15, B4-part)
+- [x] Plugin header complete: Requires at least, Requires PHP, Text
+  Domain, Domain Path present; validator returned only the Contributors
+  warning - readme parses cleanly otherwise. (D1a)
+- [x] ZIP contents otherwise reviewer-clean: no repo README, tests,
+  docs/, node_modules, or scratch; readable+minified loader pairs and all
+  five adapters present; production-only vendor/. (D2)
+
+## User-only actions before submission day
+
+1. Register/confirm the wordpress.org username matching Contributors.
+2. Re-confirm WordPress 7.0 is the current released stable.
+3. Verify basicrum.com pages linked from the listing are live.

plugins/basicrum/.distignore

@@ -8,7 +8,6 @@
 /.distignore
 
 .phpunit.result.cache
-composer.json
 composer.lock
 patchwork.json
 phpcs.ruleset.xml
@@ -24,3 +23,4 @@ playwright*.config.js
 coverage.xml
 basicrum.zip
 /release
+phpstan.neon.dist

plugins/basicrum/languages/basicrum.pot

@@ -57,7 +57,7 @@ msgid "Suggested text:"
 msgstr ""
 
 #: src/Admin/Privacy.php:48
-msgid "This site uses Basicrum to measure real-user performance. When monitoring runs, a visitor's browser sends page and resource URLs, performance and interaction timing metrics, page type, the configured site identifier, and technical browser, device, and network information to a performance collector. The collector also receives request information such as the IP address and user agent. Boomerang may use first-party cookies to maintain measurement state."
+msgid "This site uses Basicrum to measure real-user performance. When monitoring runs, a visitor's browser sends page and resource URLs, performance and interaction timing metrics, page type, the configured site identifier, and technical browser, device, and network information to a performance collector. The collector also receives request information such as the IP address and user agent. Boomerang stores measurement state in a first-party cookie named RT, which contains a random session identifier that links page views, uses SameSite=Strict, is marked Secure on HTTPS sites, and expires seven days after the last monitored page view. Opting out removes the RT cookie and any legacy BA cookie."
 msgstr ""
 
 #: src/Admin/Privacy.php:52

plugins/basicrum/readme.txt

@@ -1,5 +1,5 @@
 === Basicrum - Real User Monitoring ===
-Contributors: tstoychev
+Contributors: basicrum
 Tags: analytics, performance, rum, real-user-monitoring, web-vitals
 Requires at least: 6.0
 Tested up to: 7.0
@@ -56,7 +56,7 @@ Boomerang.js is an open source JavaScript library by Akamai that measures the pe
 
 = Do I need a Basicrum account? =
 
-Yes. You need a Basicrum collector endpoint and the matching Brum Site ID. Visit [basicrum.com](https://www.basicrum.com/) for hosted options, or use your own self-hosted collector.
+You need a Basicrum collector endpoint and the matching Brum Site ID. A hosted account from [basicrum.com](https://www.basicrum.com/) is one way to get them; running your own self-hosted collector requires no account.
 
 = Does Basicrum make my site compliant with privacy laws? =
 
@@ -76,6 +76,10 @@ Detection confirms that a supported integration is present, not that its consent
 
 By default, Basicrum may send complete query strings in page, navigation, referrer, and resource URLs. Enable **Basicrum > Visitor Privacy > Strip Query Strings** to replace them with `?qs-redacted` before sending beacons. URL paths are still collected. Review whether your URLs can contain personal or sensitive information before deciding whether to enable this setting.
 
+= Does Basicrum set cookies? =
+
+When Boomerang runs, it sets a first-party `RT` cookie that maintains timing state across consecutive pages. It uses `SameSite=Strict`, carries the `Secure` flag on HTTPS sites, and expires seven days after the last monitored page view. In **Require consent before monitoring** mode no cookie is set until your consent tool reports an allow decision, and the opt-out callback removes the `RT` cookie together with any legacy `BA` cookie left by older Boomerang setups.
+
 = Does it work with WooCommerce? =
 
 Yes. When WooCommerce is active, the plugin emits `shop`, `product`, `product_category`, `cart`, `checkout`, `checkout_payment`, `checkout_success`, and `account` page types when the corresponding WooCommerce conditional is true.
@@ -84,6 +88,14 @@ Yes. When WooCommerce is active, the plugin emits `shop`, `product`, `product_ca
 
 Yes. Enable HTTP Strictness under Basicrum's Developer Settings to preserve HTTP beacon URLs. Keep it disabled on production sites so HTTP beacon URLs are automatically upgraded to HTTPS.
 
+== External services ==
+
+This plugin sends visitor performance beacons to the collector endpoint that the site administrator configures under **Basicrum > General Settings > Beacon URL**. No beacon is sent until monitoring is enabled and, in the default **Require consent before monitoring** mode, an allow decision is reported by the site's consent tool.
+
+Each beacon carries performance data: page and resource URLs (with optional query-string redaction), timing metrics, the detected page type, and the configured Brum Site ID. As with any HTTP request, the collector also observes the visitor's IP address and user agent. Beacons go only to the configured Beacon URL; the plugin makes no requests to basicrum.com or any other service on its own.
+
+The collector can be the hosted Basicrum service or a self-hosted installation. For the hosted service, see the [Basicrum website](https://www.basicrum.com/) for service and privacy information. Operators of self-hosted collectors are responsible for their own hosting arrangements.
+
 == Third-party software ==
 
 Basicrum-owned code is licensed under the MIT License. The bundled Boomerang 1.815.60 library retains its upstream BSD license and copyright notices. See `THIRD-PARTY-NOTICES.txt` and `assets/js/boomr/LICENSE.txt` in the plugin package.
@@ -93,10 +105,4 @@ The bundled file `assets/js/boomr/boomerang-1.815.60.cutting-edge.min.js` is a m
 == Changelog ==
 
 = 0.0.8 =
-* First public release.
-* Reordered the Visitor Consent choices and hid Consent Tool Connection when consent is not required.
-* Replaced the unused consent-mode selector with clear immediate and consent-controlled loading choices.
-* Made external consent tools authoritative on every page through two explicit callbacks.
-* Added a privacy-safe default, transparent integration guidance, and WordPress Privacy Policy Guide content.
-* Added first-class query-string protection under Visitor Privacy, disabled by default.
-* Added fail-closed automatic selection for WP Consent API, Borlabs Cookie 3.2+, and the modern CookieYes plugin marker, with manual callbacks available as an explicit choice.
+* First public release: Real User Monitoring via the bundled Boomerang.js with WordPress and WooCommerce page-type detection, a consent-required default with fail-closed automatic consent-tool detection (WP Consent API, Borlabs Cookie 3.2+, CookieYes 3.x) plus manual callbacks, optional query-string redaction, editable WordPress Privacy Policy Guide text, and optimization-plugin script exclusions.

plugins/basicrum/src/Admin/Privacy.php

@@ -45,7 +45,7 @@ public function add_policy_content() {
 		$content .= '</p>';
 		$content .= '<p><strong>' . esc_html__( 'Suggested text:', 'basicrum' ) . '</strong></p>';
 		$content .= '<p>';
-		$content .= esc_html__( 'This site uses Basicrum to measure real-user performance. When monitoring runs, a visitor\'s browser sends page and resource URLs, performance and interaction timing metrics, page type, the configured site identifier, and technical browser, device, and network information to a performance collector. The collector also receives request information such as the IP address and user agent. Boomerang may use first-party cookies to maintain measurement state.', 'basicrum' );
+		$content .= esc_html__( 'This site uses Basicrum to measure real-user performance. When monitoring runs, a visitor\'s browser sends page and resource URLs, performance and interaction timing metrics, page type, the configured site identifier, and technical browser, device, and network information to a performance collector. The collector also receives request information such as the IP address and user agent. Boomerang stores measurement state in a first-party cookie named RT, which contains a random session identifier that links page views, uses SameSite=Strict, is marked Secure on HTTPS sites, and expires seven days after the last monitored page view. Opting out removes the RT cookie and any legacy BA cookie.', 'basicrum' );
 		$content .= '</p>';
 		$content .= '<p>';
 		if ( '1' === $settings['strip_query_string'] ) {

plugins/basicrum/src/Admin/Settings/Page.php

@@ -632,7 +632,7 @@ public function render_text_field( $args ) {
 			'<input id="basicrum_%1$s" name="%2$s" type="text" size="%3$d" value="%4$s" placeholder="%5$s" class="%6$s"',
 			esc_attr( $id ),
 			esc_attr( $name ),
-			$size,
+			absint( $size ),
 			esc_attr( $value ),
 			esc_attr( $placeholder ),
 			esc_attr( implode( ' ', $input_classes ) )
@@ -691,9 +691,9 @@ public function render_number_field( $args ) {
 			'<input id="basicrum_%1$s" name="%2$s" type="number" min="%3$d" max="%4$d" value="%5$d"',
 			esc_attr( $id ),
 			esc_attr( $name ),
-			$min,
-			$max,
-			$value
+			absint( $min ),
+			absint( $max ),
+			absint( $value )
 		);
 		if ( $is_disabled ) {
 			echo ' disabled="disabled"';

plugins/basicrum/src/Plugin.php

@@ -22,7 +22,6 @@ class Plugin {
 	 * @return void
 	 */
 	public function register() {
-		add_action( 'init', array( $this, 'load_textdomain' ) );
 
 		// Services loaded on every request (frontend + admin).
 		new Setup();
@@ -48,17 +47,4 @@ private function register_admin_services() {
 		new Admin\Settings\Page();
 		new Admin\Privacy();
 	}
-
-	/**
-	 * Load plugin text domain for translations.
-	 *
-	 * @return void
-	 */
-	public function load_textdomain() {
-		load_plugin_textdomain(
-			'basicrum',
-			false,
-			dirname( plugin_basename( BASICRUM_PLUGIN_FILE ) ) . '/languages'
-		);
-	}
 }

plugins/basicrum/tests/unit/PrivacyTest.php

@@ -67,6 +67,8 @@ function( $policy_title, $policy_content ) use ( &$title, &$content ) {
 		$this->assertStringContainsString( '?qs-redacted', $content );
 		$this->assertStringContainsString( 'URL paths are still collected', $content );
 		$this->assertStringContainsString( 'IP address and user agent', $content );
+		$this->assertStringContainsString( 'cookie named RT', $content );
+		$this->assertStringContainsString( 'expires seven days after the last monitored page view', $content );
 		$this->assertStringContainsString( '<code>https://collector.example.test/beacon</code>', $content );
 		$this->assertStringContainsString( 'consent tool on every page', $content );
 		$this->assertStringContainsString( 'does not persist consent across page loads', $content );

tools/verify-release.sh

@@ -38,6 +38,7 @@ require_entry 'basicrum/uninstall.php'
 require_entry 'basicrum/readme.txt'
 require_entry 'basicrum/LICENSE.md'
 require_entry 'basicrum/THIRD-PARTY-NOTICES.txt'
+require_entry 'basicrum/composer.json'
 require_entry 'basicrum/src/Plugin.php'
 require_entry 'basicrum/src/Assets.php'
 require_entry 'basicrum/src/ConsentIntegration.php'
@@ -112,7 +113,7 @@ if ! unzip -p "$ARCHIVE_PATH" basicrum/THIRD-PARTY-NOTICES.txt | grep -Fq 'Boome
 	exit 1
 fi
 
-if printf '%s\n' "$ARCHIVE_ENTRIES" | grep -Eq '^basicrum/(\.distignore|composer\.(json|lock)|package(-lock)?\.json|playwright[^/]*\.config\.(js|cjs|mjs|ts)|patchwork\.json|phpcs\.ruleset\.xml|phpunit[^/]*\.xml|README\.md|coverage\.xml|\.phpunit\.result\.cache)$'; then
+if printf '%s\n' "$ARCHIVE_ENTRIES" | grep -Eq '^basicrum/(\.distignore|composer\.lock|package(-lock)?\.json|playwright[^/]*\.config\.(js|cjs|mjs|ts)|patchwork\.json|phpcs\.ruleset\.xml|phpunit[^/]*\.xml|phpstan\.neon\.dist|README\.md|coverage\.xml|\.phpunit\.result\.cache)$'; then
 	printf '%s\n' 'Release archive contains a development file.' >&2
 	exit 1
 fi