MokoConsulting/MokoCLI
Public Access
1
0
Fork 0
Code Issues 3 Pull Requests 2 Packages Releases 8 Wiki Activity

docs: update update-server.md for push triggers, bare dev support, sync-to-main, and cascade channels

Browse Source
This commit is contained in:
Jonathan Miller
2026-04-23 19:57:28 +00:00
parent 764451d003
commit 2e97c97006
1 changed files with 59 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/workflows/update-server.md
+59 -15
View File
@@ -33,10 +33,44 @@ Joomla's `updates.xml` contains **multiple `<update>` entries simultaneously**
| Release Candidate | `<tag>rc</tag>` | Sites set to RC or lower | `update-server.yml` on `rc/**` push |
| Beta | `<tag>beta</tag>` | Sites set to Beta or lower | `update-server.yml` on `beta/**` push |
| Alpha | `<tag>alpha</tag>` | Sites set to Alpha or lower | `update-server.yml` on `alpha/**` push |
| Development | `<tag>development</tag>` | Sites set to Development | `update-server.yml` on `dev/**` push |
| Development | `<tag>development</tag>` | 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 `<tag>development</tag>` 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 `<update>` entries from the XML file but only presents entries whose `<tag>` 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
<tags>
<tag>development</tag>
</tags>
<infourl title="My Extension">https://github.com/org/repo/tree/dev/01.04</infourl>
<infourl title="My Extension">https://git.mokoconsulting.tech/MokoConsulting/MyExtension/src/branch/dev</infourl>
<downloads>
<downloadurl type="full" format="zip">https://github.com/org/repo/archive/refs/heads/dev/01.04.zip</downloadurl>
<downloadurl type="full" format="zip">https://git.mokoconsulting.tech/MokoConsulting/MyExtension/releases/download/development/com_myextension-01.04.00-dev.zip</downloadurl>
</downloads>
<targetplatform name="joomla" version="((4\.[3-9])|(5\.[0-9]))" />
<maintainer>Moko Consulting</maintainer>
@@ -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` | `<tag>stable</tag>` — writes the stable entry with SHA-256 hash of the ZIP |
| `update-server.yml` | Push to `rc/**` | `<tag>rc</tag>` — adds/updates the RC entry |
| `update-server.yml` | Push to `beta/**` | `<tag>beta</tag>` — adds/updates the beta entry |
| `update-server.yml` | Push to `alpha/**` | `<tag>alpha</tag>` — adds/updates the alpha entry |
| `update-server.yml` | Push to `dev/**` | `<tag>development</tag>` — adds/updates the development entry |
| `update-server.yml` | Push to `rc/**` | `<tag>rc</tag>` — adds/updates the RC entry (+ cascaded lower channels) |
| `update-server.yml` | Push to `beta/**` | `<tag>beta</tag>` — adds/updates the beta entry (+ cascaded lower channels) |
| `update-server.yml` | Push to `alpha/**` | `<tag>alpha</tag>` — adds/updates the alpha entry (+ cascaded lower channels) |
| `update-server.yml` | Push to `dev` or `dev/**` | `<tag>development</tag>` — 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 `<updateservers>` 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 `<tag>stable</tag>` 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 `<tag>rc</tag>` 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 `<tag>beta</tag>` 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 `<tag>alpha</tag>` 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 `<tag>development</tag>` 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)