From 2e97c970062102c786821b34b0fa235a49cc5bca Mon Sep 17 00:00:00 2001 From: Jonathan Miller Date: Thu, 23 Apr 2026 19:57:28 +0000 Subject: [PATCH] docs: update update-server.md for push triggers, bare dev support, sync-to-main, and cascade channels --- docs/workflows/update-server.md | 74 ++++++++++++++++++++++++++------- 1 file changed, 59 insertions(+), 15 deletions(-) diff --git a/docs/workflows/update-server.md b/docs/workflows/update-server.md index bc10319..f5a4aef 100644 --- a/docs/workflows/update-server.md +++ b/docs/workflows/update-server.md @@ -33,10 +33,44 @@ Joomla's `updates.xml` contains **multiple `` entries simultaneously** | Release Candidate | `rc` | Sites set to RC or lower | `update-server.yml` on `rc/**` push | | Beta | `beta` | Sites set to Beta or lower | `update-server.yml` on `beta/**` push | | Alpha | `alpha` | Sites set to Alpha or lower | `update-server.yml` on `alpha/**` push | -| Development | `development` | Sites set to Development | `update-server.yml` on `dev/**` push | +| Development | `development` | Sites set to Development | `update-server.yml` on `dev` or `dev/**` push | **Note**: Alpha and beta are optional stages. Not every release cycle will have alpha/beta entries. +### `update-server.yml` Trigger Behavior + +The `update-server.yml` workflow triggers on **both direct pushes and PR merges** to the following branches: + +- `dev` (bare branch — no sub-path required) +- `dev/**` (versioned dev branches like `dev/02.01`) +- `alpha/**` +- `beta/**` +- `rc/**` + +Previously, the workflow only triggered on PR merges. The addition of push triggers ensures that direct commits to these branches (e.g., CI-generated version bumps, automated fixes) also update the `updates.xml` entries. + +### Cascade Release Channels + +Each stability level writes its own channel **and all lower channels** to `updates.xml`. This ensures Joomla sites on any "Minimum Stability" setting always see the latest available release: + +| Release Stream | Channels written to updates.xml | +|---------------|-------------------------------| +| development | `development` | +| alpha | `development`, `alpha` | +| beta | `development`, `alpha`, `beta` | +| rc | `development`, `alpha`, `beta`, `rc` | +| stable | `development`, `alpha`, `beta`, `rc`, `stable` | + +Without cascade, a site set to "Development" minimum stability would only see `development` entries and would miss stable releases entirely. The cascade ensures stable releases are visible to all sites regardless of their minimum stability setting. + +For full cascade documentation, see [Cascade Release Channels](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards/src/branch/main/docs/release-management/cascade-channels.md). + +### Sync to Main + +Since Joomla sites read `updates.xml` from the `main` branch, the `update-server.yml` workflow **syncs `updates.xml` to `main` via the Gitea API** after building on non-main branches. This ensures pre-release channel entries (dev, alpha, beta, rc) are visible to sites checking for updates, without requiring a PR merge to main. + +Previously, `update-server.yml` only committed `updates.xml` to the current branch, so Joomla sites never saw dev/alpha/beta/rc releases until they were merged to main. + ### How Joomla Filters Updates Joomla's update system reads all `` entries from the XML file but only presents entries whose `` matches the site's minimum stability threshold: @@ -66,7 +100,7 @@ dev → [alpha] → [beta] → rc → version/XX → main → dev optional optional (integration) (production) (feedback) ``` -- **`dev/**`**: Active development. Update files tagged as `development`. +- **`dev` or `dev/**`**: Active development. Update files tagged as `development`. - **`alpha/**`**: *(Optional)* Early internal testing. Update files tagged as `alpha`. Can be skipped. - **`beta/**`**: *(Optional)* Broader external testing. Update files tagged as `beta`. Can be skipped. - **`rc/**`**: Release candidate. Update files tagged as `rc`. RC branches deploy to dev server for final testing. @@ -105,7 +139,7 @@ The `updates.xml` file contains **up to five stability entries at once** (one pe ### Platform Distribution | Release Type | Gitea Release | GitHub Release | Download URLs | -|-------------|--------------|----------------|---------------| +|-------------|---------------|----------------|---------------| | **Stable** | Yes | Yes (via mirror) | Dual (Gitea + GitHub) | | **RC** | Yes | No | Single (Gitea only) | | **Beta** | Yes | No | Single (Gitea only) | @@ -206,9 +240,9 @@ Pre-release builds stay on Gitea for internal testing. Only stable releases are development - https://github.com/org/repo/tree/dev/01.04 + https://git.mokoconsulting.tech/MokoConsulting/MyExtension/src/branch/dev - https://github.com/org/repo/archive/refs/heads/dev/01.04.zip + https://git.mokoconsulting.tech/MokoConsulting/MyExtension/releases/download/development/com_myextension-01.04.00-dev.zip Moko Consulting @@ -222,12 +256,14 @@ Pre-release builds stay on Gitea for internal testing. Only stable releases are | Workflow | Trigger | Entry written | |----------|---------|---------------| | `auto-release.yml` | Push to `main` | `stable` — writes the stable entry with SHA-256 hash of the ZIP | -| `update-server.yml` | Push to `rc/**` | `rc` — adds/updates the RC entry | -| `update-server.yml` | Push to `beta/**` | `beta` — adds/updates the beta entry | -| `update-server.yml` | Push to `alpha/**` | `alpha` — adds/updates the alpha entry | -| `update-server.yml` | Push to `dev/**` | `development` — adds/updates the development entry | +| `update-server.yml` | Push to `rc/**` | `rc` — adds/updates the RC entry (+ cascaded lower channels) | +| `update-server.yml` | Push to `beta/**` | `beta` — adds/updates the beta entry (+ cascaded lower channels) | +| `update-server.yml` | Push to `alpha/**` | `alpha` — adds/updates the alpha entry (+ cascaded lower channels) | +| `update-server.yml` | Push to `dev` or `dev/**` | `development` — adds/updates the development entry | -The `auto-release.yml` workflow writes the stable entry and preserves any existing pre-release entries. The `update-server.yml` workflow writes only its specific entry (rc, beta, alpha, or dev) and preserves the others. +The `auto-release.yml` workflow writes the stable entry and preserves any existing pre-release entries. The `update-server.yml` workflow writes its specific entry (and cascaded lower channels) and preserves the others. + +**Important**: All `update-server.yml` runs also sync the updated `updates.xml` to `main` via the Gitea API, since Joomla sites read the update server XML from the `main` branch. ### XML Elements @@ -278,32 +314,40 @@ The `` tag tells Joomla where to check for updates. Both servers - Uploads ZIP to the `vXX` major release on GitHub - Computes SHA-256 hash of the ZIP - Writes/updates the `stable` entry in `updates.xml` with version, download URL, and SHA-256 + - Cascades to all 5 stability channels - Preserves any existing rc/dev entries in the file - Commits updated `updates.xml` to main 2. **On RC push** (`update-server.yml` → rc/** branches): - Writes/updates the `rc` entry in `updates.xml` - - Download URL points to the branch archive ZIP + - Cascades to `rc`, `beta`, `alpha`, and `development` channels + - Download URL points to the Gitea release ZIP - Preserves all other stability entries - Commits updated `updates.xml` to the rc branch + - **Syncs `updates.xml` to `main` via Gitea API** 3. **On beta push** (`update-server.yml` → beta/** branches): - Writes/updates the `beta` entry in `updates.xml` - - Download URL points to the branch archive ZIP + - Cascades to `beta`, `alpha`, and `development` channels + - Download URL points to the Gitea release ZIP - Preserves all other stability entries - Commits updated `updates.xml` to the beta branch + - **Syncs `updates.xml` to `main` via Gitea API** 4. **On alpha push** (`update-server.yml` → alpha/** branches): - Writes/updates the `alpha` entry in `updates.xml` - - Download URL points to the branch archive ZIP + - Cascades to `alpha` and `development` channels + - Download URL points to the Gitea release ZIP - Preserves all other stability entries - Commits updated `updates.xml` to the alpha branch + - **Syncs `updates.xml` to `main` via Gitea API** -5. **On dev push** (`update-server.yml` → dev/** branches): +5. **On dev push** (`update-server.yml` → `dev` or `dev/**` branches): - Writes/updates the `development` entry in `updates.xml` - - Download URL points to the branch archive ZIP + - Download URL points to the Gitea release ZIP - Preserves all other stability entries - Commits updated `updates.xml` to the dev branch + - **Syncs `updates.xml` to `main` via Gitea API** ### Dolibarr (update.txt)