Beta channel scaffold

2026-07-23 23:43:18 -04:00
commit 6c34d89a2f
14 changed files with 647 additions and 0 deletions
@@ -0,0 +1,111 @@
+# Beta channel — one-time setup runbook
+
+Goal: stand up a beta feed that Q-SYS testers can add without touching the
+production feed. You do this once; after that, publishing a beta is just the
+five steps in the README.
+
+Placeholders used below (matching your production setup):
+- Gitea host: `3f4dzl.gitea.cloud`
+- Org: `visionary-plugins`
+- Beta package id: `Visionary-PacketAV-Suite-Beta`
+
+---
+
+## 1. Create the beta repo in Gitea
+
+Same org as production (packages are owned by the org, so the beta package will
+sit alongside prod in the org's Packages list — that's expected).
+
+1. In Gitea: **`visionary-plugins` org → New Repository**.
+2. Name it `qsys-plugin-registry-beta`. Set visibility however you like —
+   **repo visibility does not affect the feed.** The package feed's anonymous
+   readability comes from the **org** being Public, which it already is for
+   prod. (If the org is Public, the beta package is anonymously readable too.)
+3. Push this scaffold to it:
+
+   ```bash
+   cd qsys-plugin-registry-beta
+   git init -b main
+   git add .
+   git commit -m "Beta channel scaffold"
+   git remote add origin https://3f4dzl.gitea.cloud/visionary-plugins/qsys-plugin-registry-beta.git
+   git push -u origin main
+   ```
+
+## 2. Add the publish token
+
+Same token as production works — a Gitea PAT with **package read/write** scope
+is org-wide, so it can publish `Visionary-PacketAV-Suite-Beta` too.
+
+- Beta repo → **Settings → Actions → Secrets** → add **`PACKAGE_TOKEN`** with
+  the same value you used for the prod repo.
+- Confirm a runner is available to the repo (Settings → Actions).
+
+## 3. Publish a first beta build
+
+1. Put a beta `.qplugx` set (or just copy the current prod content for a
+   smoke test) + `icon.png` into
+   `plugins/VisionarySolutions_Suite_Beta/content/`.
+2. Commit and push.
+3. Actions → **Publish Q-SYS plugins → Run workflow**.
+4. Verify the feed the same way as prod, anonymously:
+
+   ```bash
+   curl https://3f4dzl.gitea.cloud/api/packages/visionary-plugins/nuget/registration/Visionary-PacketAV-Suite-Beta/index.json
+   ```
+
+   You should see JSON listing the beta version(s).
+
+## 4. Cloudflare short-links (301 redirects)
+
+Add two aliases next to your existing `packetav` / `versions` rules. Point them
+at the beta package's registration URL and the beta versions file.
+
+| Short link | 301 target |
+|---|---|
+| `vsplug.in/packetav-beta` | `https://3f4dzl.gitea.cloud/api/packages/visionary-plugins/nuget/registration/Visionary-PacketAV-Suite-Beta/index.json` |
+| `vsplug.in/versions-beta` | raw URL of `versions-beta.json` in your assets repo, e.g. `https://3f4dzl.gitea.cloud/visionary-plugins/assets/raw/branch/main/versions-beta.json` |
+
+Then, in a browser (logged out), open `https://vsplug.in/packetav-beta` and
+confirm it lands on the registration JSON — QSC's backend must be able to
+follow the redirect, exactly as it does for the prod link.
+
+## 5. Seed the beta update feed
+
+Put `versions-beta.json` (in this repo's `docs/`) into the **assets** repo root
+so `vsplug.in/versions-beta` resolves. Keep its `package` value equal to the
+beta nuspec `<version>` and the `plugins` map equal to the beta build's plugin
+versions. Update it every time you publish a new beta.
+
+## 6. Beta icon (optional but recommended)
+
+The nuspec references `icon-beta.png` in the assets repo so beta is visually
+distinct in Asset Installer. Drop a beta-badged icon there, or change the
+`iconUrl` back to the prod `icon.png` if you'd rather not bother.
+
+---
+
+## Version lineage rules (same discipline as prod)
+
+- Beta `<version>` is **3-part SemVer only** — a 4-part number makes the whole
+  package vanish from Asset Installer.
+- Strictly ascending. The beta counter is **independent** of the prod counter;
+  don't try to keep them in sync.
+- No prerelease `-beta` suffix on the number itself — Q-SYS filters those. The
+  channel separation is the package id, not a version tag.
+
+## Promotion flow (beta → production)
+
+1. Copy the **same** `.qplugx` files from the beta `content/` into the prod
+   repo's `content/`.
+2. Bump the **production** nuspec `<version>`.
+3. Commit/push and run the prod publish workflow.
+4. Update the prod `versions.json`.
+
+Because the plugin files (and their PluginInfo.Ids) are byte-identical, this is
+a re-wrap, not a rebuild — what testers validated is exactly what ships.
+
+## Retiring a beta build
+
+Delete old beta versions from the org's Packages page anytime — beta has no
+field-install guarantees, so same-version delete/republish is fine here.