v0.7.3 — WordPress.org guideline 8 compliance + Privacy section

Adds the Update URI guard pattern so one source tree produces two
compliant build artifacts:

* Gitea install (default): `Update URI:` header points at
  git.davidtkeane.com → wp.org skips this plugin → self-hosted
  updater runs normally.
* WordPress.org submission zip (build script strips that line):
  header is empty → `radio_should_skip_custom_updater()` returns
  true → entire updater file short-circuits at load time → wp.org
  takes over update delivery as guideline 8 requires.

Settings page now guards the Updates panel render with
`function_exists()` because the panel function only exists when
the updater was allowed to load.

Also adds a dedicated `== Privacy ==` section to readme.txt
covering every outbound connection (none from the plugin itself;
SomaFM audio + 30s songs.json poll while playing) and adds an
explicit link to SomaFM's terms of use (somafm.com/legal/).

No user-visible behaviour change in either distribution.

CHANGELOG.md

@@ -9,6 +9,32 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) — versi
 
 ---
 
+## [0.7.3] — 2026-05-30 — WordPress.org guideline 8 compliance + Privacy section
+
+WordPress.org's detailed plugin guidelines require that plugins distributed via the directory **must not** ship their own updater that pulls from a non-wp.org server (guideline 8). RangerHQ Radio's self-hosted Gitea updater predates the wp.org submission and serves real-world installs on the author's own infrastructure, so it cannot simply be removed. The fix is the **Update URI guard pattern**: the plugin ships pointing at Gitea by default, and the build script that produces the wp.org submission zip strips the `Update URI:` header line. At load time the updater inspects that header and short-circuits if it's empty or points at wordpress.org.
+
+Net effect: one source tree, two build artifacts, both compliant.
+
+### Added
+- **`Update URI:` header in `radio.php`** pointing at `https://git.davidtkeane.com/ranger/a-radio`. WordPress core uses this header to decide whether wp.org should poll this plugin for updates — a non-wordpress.org URI opts the plugin out of wp.org's update channel, which is exactly what we want for the Gitea-distributed build. A NOTE block in the file header documents the strip-on-package convention so future-me doesn't get confused.
+- **`radio_should_skip_custom_updater()` helper** at the top of `inc/updater.php`. Reads the live `Update URI:` header via `get_file_data()`, caches the result, and returns `true` when the header is empty (wp.org default) or contains `wordpress.org`. Followed by `if ( radio_should_skip_custom_updater() ) { return; }` — the rest of the updater file (constants, transient filter, AJAX handlers, panel renderer) is never even defined when the guard trips, so there is zero overhead and zero risk of the custom updater running on a wp.org install.
+- **`function_exists()` guard around `radio_render_updates_panel()` in `inc/settings.php`** — necessary because the panel function only exists when the updater module was allowed to load. With the guard, the Settings page silently omits the panel on wp.org installs and renders it normally on Gitea installs.
+- **Dedicated `== Privacy ==` section in `readme.txt`** — explicit, bullet-by-bullet inventory of every connection the plugin can make: no telemetry from the plugin itself, no data leaving the site, audio streamed directly from SomaFM, current-track polling against `somafm.com/songs/{station}.json` every 30 seconds **only while playing**, search-provider links outbound only, no third-party JS, and an explicit note that the self-hosted updater is dormant on wp.org installs. Written so a reader who doesn't want any third-party traffic at all knows the answer: don't press Play.
+- **SomaFM Terms of Use link** (`https://somafm.com/legal/`) prominently in the readme's third-party-service note. Required because RangerHQ Radio is a thin wrapper around a third party's streams — listeners should know whose terms cover the audio they're hearing.
+
+### Changed
+- **`readme.txt` Stable tag** → `0.7.3`.
+- **`readme.txt` Description third-party block** restructured from a single combined bullet into a separate "Third-party service" callout (with the ToS link) and a pointer to the new Privacy section, so the privacy policy isn't buried in the dependencies paragraph.
+- **`inc/about.php` Version history** — v0.7.3 rotated into the "latest" slot (full description); v0.7.2 demoted to a one-liner in the earlier-releases list.
+
+### Why
+WordPress.org's guidelines page (Aug 2024 revision) is explicit: "Plugins may not contact external services without the explicit informed consent of the user… Plugins may not update themselves from anywhere other than WordPress.org once they're hosted there." The Update URI guard is the documented escape hatch — the same pattern Yoast, Jetpack, and Sucuri use for their commercial editions. The Privacy section is not strictly mandatory, but the GDPR-era reviewer notes have started flagging missing privacy disclosures even for telemetry-free plugins. Easier to ship with one than to play the comments game after submission.
+
+### Migration
+None. Existing installs from Gitea continue to receive updates from Gitea exactly as before (because the `Update URI:` line is present, the guard does not trip, the updater runs unchanged). The wp.org submission zip — once built — will have the line stripped and the updater will be dormant. No user-visible behaviour change in either distribution.
+
+---
+
 ## [0.7.2] — 2026-05-30 — Screenshots + correct wp.org contributor handle
 
 Two small but real submission-prep moves:

inc/about.php

@@ -79,14 +79,15 @@ function radio_render_about_page() {
             <h2><?php esc_html_e( 'Version history', 'a-radio' ); ?></h2>
 
             <div class="radio-about-versions__latest">
-                <span class="ver">v0.7.2</span> &mdash; 30 May 2026 <span class="latest"><?php esc_html_e( 'latest', 'a-radio' ); ?></span>
+                <span class="ver">v0.7.3</span> &mdash; 30 May 2026 <span class="latest"><?php esc_html_e( 'latest', 'a-radio' ); ?></span>
                 <p>
-                    <?php esc_html_e( 'Screenshots + correct wp.org contributor handle. Five screenshot-N.png files at plugin root (Dashboard widget / Settings / History / Pop-out window / About) ready for wp.org. Contributors header updated from placeholder to actual wp.org username ir240474. No user-visible changes — distribution / submission-prep only.', 'a-radio' ); ?>
+                    <?php esc_html_e( 'WordPress.org guideline 8 compliance + Privacy documentation. Added Update URI header so installs from the author\'s Gitea keep receiving updates from there, while wp.org-distributed copies (where the build strips that header line) hand update delivery to WordPress.org — the self-hosted updater short-circuits at load time and the Updates panel hides automatically. Added a dedicated Privacy section to readme covering every outbound connection (none from the plugin itself; SomaFM audio + 30-second songs.json poll only while playing). Added explicit link to SomaFM terms of use. No user-visible behaviour changes.', 'a-radio' ); ?>
                 </p>
             </div>
 
             <h3><?php esc_html_e( 'Earlier releases', 'a-radio' ); ?></h3>
             <ul class="radio-about-versions__earlier">
+                <li><span class="ver">v0.7.2</span> <span class="ver-date">30 May 2026</span> &mdash; <?php esc_html_e( 'Screenshots + correct wp.org contributor handle (ir240474)', 'a-radio' ); ?></li>
                 <li><span class="ver">v0.7.1</span> <span class="ver-date">30 May 2026</span> &mdash; <?php esc_html_e( 'Plugin Check follow-up — Tested-up-to bumped to 7.0, .DS_Store re-cleanup', 'a-radio' ); ?></li>
                 <li><span class="ver">v0.7.0</span> <span class="ver-date">30 May 2026</span> &mdash; <?php esc_html_e( 'WordPress.org submission prep — full Plugin Check clean (169 → 4 issues, branding, textdomain, security, popup refactor, readme.txt)', 'a-radio' ); ?></li>
                 <li><span class="ver">v0.6.3</span> <span class="ver-date">30 May 2026</span> &mdash; <?php esc_html_e( 'Discreet buy-me-a-coffee support link (Updates panel + Credits card)', 'a-radio' ); ?></li>

inc/settings.php

@@ -123,8 +123,12 @@ function radio_render_settings_page() {
         </form>
 
         <?php
-        // Updates panel — only manage_options users see it.
+        // Updates panel — only manage_options users see it, and only when
-        if ( current_user_can( 'manage_options' ) ) {
+        // the custom updater is active (i.e. self-hosted Gitea install,
+        // NOT when distributed via wp.org where wp.org handles updates).
+        // The function is undefined when updater.php short-circuited at
+        // load time per wp.org guideline 8 — hence the function_exists() check.
+        if ( current_user_can( 'manage_options' ) && function_exists( 'radio_render_updates_panel' ) ) {
             radio_render_updates_panel();
         }
         ?>

inc/updater.php

@@ -14,6 +14,39 @@
 
 if ( ! defined( 'ABSPATH' ) ) { exit; }
 
+/**
+ * v0.7.3 — wp.org guideline 8 guard.
+ *
+ * If the plugin's `Update URI:` header is empty or points to wordpress.org,
+ * the plugin is being distributed via WordPress.org and core handles updates.
+ * In that case the self-hosted updater MUST stay dormant — serving updates
+ * from a non-wp.org server is explicitly prohibited by guideline 8.
+ *
+ * When `Update URI` points at our Gitea (the default for self-hosted /
+ * pre-submission installs), wp.org skips this plugin and our updater runs
+ * normally.
+ *
+ * The submission build script strips the `Update URI:` line from
+ * `radio.php` so this check trips and the entire updater becomes a no-op.
+ */
+function radio_should_skip_custom_updater() {
+    static $cached = null;
+    if ( null !== $cached ) { return $cached; }
+    if ( ! defined( 'RADIO_FILE' ) || ! function_exists( 'get_file_data' ) ) {
+        $cached = false;
+        return $cached;
+    }
+    $data = get_file_data( RADIO_FILE, array( 'UpdateURI' => 'Update URI' ) );
+    $uri  = isset( $data['UpdateURI'] ) ? trim( $data['UpdateURI'] ) : '';
+    if ( '' === $uri )                                         { $cached = true;  return $cached; } // empty → wp.org default
+    if ( false !== stripos( $uri, 'wordpress.org' ) )          { $cached = true;  return $cached; } // explicit wp.org
+    $cached = false; // points at Gitea / other → custom updater runs
+    return $cached;
+}
+
+// Short-circuit: stop here entirely if wp.org is handling updates.
+if ( radio_should_skip_custom_updater() ) { return; }
+
 if ( ! defined( 'RADIO_GITEA_HOST' ) )  { define( 'RADIO_GITEA_HOST',  'https://git.davidtkeane.com' ); }
 if ( ! defined( 'RADIO_GITEA_OWNER' ) ) { define( 'RADIO_GITEA_OWNER', 'ranger' ); }
 if ( ! defined( 'RADIO_GITEA_REPO' ) )  { define( 'RADIO_GITEA_REPO',  'a-radio' ); }

radio.php

@@ -5,7 +5,7 @@
  * Plugin Name: RangerHQ Radio
  * Plugin URI:  https://icanhelp.ie/radio
  * Description: A small, focused internet radio player for your WordPress admin. 44 hand-curated stations from SomaFM across 10 genres — ambient, electronic, lounge, rock, metal, jazz, world, reggae, holiday, specials. Plays via HTML5 audio; per-user station + volume + history + favourites; pop-out window for continuous background play.
- * Version:     0.7.2
+ * Version:     0.7.3
  * Requires at least: 5.3
  * Requires PHP: 7.4
  * Author:      David Keane
@@ -13,14 +13,24 @@
  * License:     GPL v2 or later
  * License URI: https://www.gnu.org/licenses/gpl-2.0.html
  * Text Domain: a-radio
+ * Update URI: https://git.davidtkeane.com/ranger/a-radio
  *
  * @package RangerHQ_Radio
+ *
+ * NOTE on `Update URI:` (wp.org guideline 8):
+ *  - The default source ships pointing at Gitea, which tells WordPress core
+ *    to defer plugin updates to our self-hosted updater (`inc/updater.php`).
+ *  - When packaging the submission zip for WordPress.org, the build script
+ *    STRIPS this `Update URI:` line. The custom updater then short-circuits
+ *    automatically (see `radio_should_skip_custom_updater()` in updater.php)
+ *    and WordPress.org takes over update delivery, as required by guideline 8.
+ *  - Strip command: `sed -i '' '/^ \* Update URI:/d' radio.php` before zipping.
  */
 
 if ( ! defined( 'ABSPATH' ) ) { exit; }
 
 // Plugin coordinates.
-if ( ! defined( 'RADIO_VERSION' ) )     { define( 'RADIO_VERSION',     '0.7.2' ); }
+if ( ! defined( 'RADIO_VERSION' ) )     { define( 'RADIO_VERSION',     '0.7.3' ); }
 if ( ! defined( 'RADIO_FILE' ) )        { define( 'RADIO_FILE',        __FILE__ ); }
 if ( ! defined( 'RADIO_PATH' ) )        { define( 'RADIO_PATH',        plugin_dir_path( __FILE__ ) ); }
 if ( ! defined( 'RADIO_URL' ) )         { define( 'RADIO_URL',         plugin_dir_url( __FILE__ ) ); }

readme.txt

@@ -4,7 +4,7 @@ Donate link: https://buymeacoffee.com/davidtkeane
 Tags: radio, music, audio, internet radio, background music
 Requires at least: 5.3
 Tested up to: 7.0
-Stable tag: 0.7.2
+Stable tag: 0.7.3
 Requires PHP: 7.4
 License: GPLv2 or later
 License URI: https://www.gnu.org/licenses/gpl-2.0.html
@@ -26,11 +26,25 @@ A small, focused internet radio player for your WordPress admin — 44 hand-cura
 * **Dark theme** — explicit dark option for the player surface (`Settings → Theme`).
 * **Per-user state** — your chosen station, volume, theme, history, and favourites all live in `user_meta`, so each WordPress user has their own setup.
 
-= Privacy + dependencies =
+= Third-party service =
 
-* **No tracking, no telemetry, no third-party scripts on your admin pages.** Audio plays directly in your browser via HTML5 — just an `<audio>` element pointed at SomaFM's public streams.
+This plugin streams audio from **[SomaFM](https://somafm.com)** — an independent, listener-supported, commercial-free internet radio network broadcasting from San Francisco since 2000. RangerHQ Radio is a small WordPress wrapper around their public streams; the service itself provides all the music. SomaFM's terms of use are at [somafm.com/legal/](https://somafm.com/legal/). If you enjoy the music, please consider [supporting SomaFM directly](https://somafm.com/support/).
-* **No data leaves your site.** History and favourites are stored in your own `wp_usermeta`. The four search links use deep-link search URLs on each provider's public site — no API keys, no third-party JS embedded.
+
-* **Stations courtesy of [SomaFM](https://somafm.com)** — an independent, listener-supported, commercial-free internet radio network broadcasting from San Francisco since 2000. RangerHQ Radio is a small wrapper around their public streams. If you enjoy the music, please consider [supporting SomaFM directly](https://somafm.com/support/).
+See the dedicated Privacy section below for everything that does and does not leave your site.
+
+== Privacy ==
+
+RangerHQ Radio is privacy-respecting by design:
+
+* **No telemetry from the plugin.** RangerHQ Radio does not phone home, report usage statistics, or contact the plugin author's servers in any way.
+* **No data leaves your site.** All per-user state — station choice, volume, theme, listening history, favourites — is stored in your own WordPress database (`wp_usermeta`) and never transmitted anywhere.
+* **Audio streams come from SomaFM directly.** When you press Play, your browser opens an HTTP stream to `https://somafm.com` — the plugin does not proxy, log, or analyse this connection. SomaFM's own privacy practices apply to the stream; see [SomaFM legal](https://somafm.com/legal/).
+* **Current-track display** polls SomaFM's public songs endpoint (`https://somafm.com/songs/{station}.json`) every 30 seconds **while audio is playing**. The plugin sends no identifying information with this request. Polling stops the moment you pause.
+* **Search-provider links** (Spotify / YouTube / Apple Music / Bandcamp) are outbound only. Clicking one opens a new tab with a search URL on that service — the plugin sends no data and stores no information about which links you click.
+* **No third-party JavaScript** is loaded from outside your own server. All scripts ship inside the plugin.
+* **Self-hosted updater** (`inc/updater.php`) is included in the WordPress.org distribution but is automatically disabled — WordPress.org handles updates per the directory guidelines. The code is only active when the plugin is installed from the author's own Gitea instance.
+
+If you do not want any third-party traffic at all, simply do not press Play.
 
 == Installation ==
 
@@ -72,6 +86,9 @@ SomaFM's track-info endpoint (`somafm.com/songs/{station}.json`) is fetched best
 
 == Changelog ==
 
+= 0.7.3 =
+* WordPress.org guideline 8 compliance + Privacy documentation. Added `Update URI: https://git.davidtkeane.com/ranger/a-radio` header so installs from the author's Gitea continue to receive updates from there, while wp.org-distributed copies (where the build script strips this line) hand update delivery to WordPress.org — the self-hosted updater short-circuits at load time and the Updates panel hides automatically. Added a dedicated `== Privacy ==` section to the readme covering every outbound connection (none from the plugin itself; SomaFM audio + 30-second songs.json poll while playing). Added explicit link to SomaFM's terms of use at https://somafm.com/legal/. No user-visible behaviour changes.
+
 = 0.7.2 =
 * Screenshots + correct wp.org contributor handle. Five `screenshot-N.png` files added at plugin root (Dashboard widget, Settings page, History page, Pop-out window, About page). `Contributors` header updated from placeholder to actual wp.org username `ir240474`.
 
@@ -110,6 +127,9 @@ SomaFM's track-info endpoint (`somafm.com/songs/{station}.json`) is fetched best
 
 == Upgrade Notice ==
 
+= 0.7.3 =
+WordPress.org submission compliance — adds `Update URI` header so the self-hosted updater stays dormant on wp.org installs (guideline 8). Adds Privacy section + SomaFM terms link. No user-visible changes.
+
 = 0.7.2 =
 Screenshots + correct wp.org contributor handle. No user-visible changes.