# 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.