Jonathan Miller
0d280717f1
Universal: Cascade Main → Dev / Cascade main → branches (push) Successful in 1s
This reverts commita45a6cb59c, reversing changes made to018b197147.
144 lines
6.2 KiB
Markdown
144 lines
6.2 KiB
Markdown
<!--
|
|
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
|
|
|
|
This file is part of a Moko Consulting project.
|
|
|
|
SPDX-License-Identifier: GPL-3.0-or-later
|
|
|
|
# FILE INFORMATION
|
|
DEFGROUP: MokoWaaS.Documentation
|
|
INGROUP: MokoStandards.Templates
|
|
REPO: https://github.com/mokoconsulting-tech/MokoWaaS
|
|
PATH: /docs/update-server.md
|
|
VERSION: 02.01.08
|
|
BRIEF: How this extension's Joomla update server file (update.xml) is managed
|
|
-->
|
|
|
|
# Joomla Update Server
|
|
|
|
[](https://github.com/mokoconsulting-tech/MokoStandards)
|
|
|
|
This document explains how `update.xml` is automatically managed for this Joomla extension following the [Joomla Update Server specification](https://docs.joomla.org/Deploying_an_Update_Server).
|
|
|
|
## How It Works
|
|
|
|
Joomla checks for extension updates by fetching an XML file from the URL defined in the `<updateservers>` tag in the extension's XML manifest. MokoStandards generates this file automatically.
|
|
|
|
### Automatic Generation
|
|
|
|
| Event | Workflow | `<tag>` | `<version>` |
|
|
|-------|----------|---------|-------------|
|
|
| Merge to `main` | `auto-release.yml` | `stable` | `XX.YY.ZZ` |
|
|
| Push to `dev` or `dev/**` | `update-server.yml` | `development` | `XX.YY.ZZ-dev` |
|
|
| Push to `alpha/**` | `update-server.yml` | `alpha` | `XX.YY.ZZ-alpha` |
|
|
| Push to `beta/**` | `update-server.yml` | `beta` | `XX.YY.ZZ-beta` |
|
|
| Push to `rc/**` | `update-server.yml` | `rc` | `XX.YY.ZZ-rc` |
|
|
|
|
**Trigger behavior**: `update-server.yml` triggers on both direct pushes and PR merges to `dev`, `dev/**`, `alpha/**`, `beta/**`, and `rc/**` branches. It supports bare `dev` branches (not just `dev/**` patterns).
|
|
|
|
### Cascade Release Channels
|
|
|
|
Each stability level writes itself **and all lower channels** to `updates.xml`:
|
|
|
|
| Release Stream | Channels written |
|
|
|---------------|-----------------|
|
|
| development | `development` |
|
|
| alpha | `development`, `alpha` |
|
|
| beta | `development`, `alpha`, `beta` |
|
|
| rc | `development`, `alpha`, `beta`, `rc` |
|
|
| stable | `development`, `alpha`, `beta`, `rc`, `stable` |
|
|
|
|
This ensures Joomla sites on any "Minimum Stability" setting always see the latest available release.
|
|
|
|
### 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 are visible to sites checking for updates without requiring a PR merge to main.
|
|
|
|
### Generated XML Structure
|
|
|
|
```xml
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<updates>
|
|
<update>
|
|
<name>Extension Name</name>
|
|
<description>Extension Name update</description>
|
|
<element>com_extensionname</element>
|
|
<type>component</type>
|
|
<version>01.02.03</version>
|
|
<client>site</client>
|
|
<folder>system</folder> <!-- plugins only -->
|
|
<tags>
|
|
<tag>stable</tag>
|
|
</tags>
|
|
<infourl title="Extension Name">https://github.com/.../releases/tag/v01.02.03</infourl>
|
|
<downloads>
|
|
<downloadurl type="full" format="zip">https://github.com/.../releases/download/v01.02.03/com_ext-01.02.03.zip</downloadurl>
|
|
</downloads>
|
|
<targetplatform name="joomla" version="((5\.[0-9])|(6\.[0-9]))" />
|
|
<php_minimum>8.2</php_minimum> <!-- if present in manifest -->
|
|
<maintainer>Moko Consulting</maintainer>
|
|
<maintainerurl>https://mokoconsulting.tech</maintainerurl>
|
|
</update>
|
|
</updates>
|
|
```
|
|
|
|
### Metadata Source
|
|
|
|
All metadata is extracted from the extension's XML manifest (`src/*.xml`) at build time:
|
|
|
|
| XML Element | Source | Notes |
|
|
|-------------|--------|-------|
|
|
| `<name>` | `<name>` in manifest | Extension display name |
|
|
| `<element>` | `<element>` in manifest | Must match installed extension identifier |
|
|
| `<type>` | `type` attribute on `<extension>` | `component`, `module`, `plugin`, `library`, `package`, `template` |
|
|
| `<client>` | `client` attribute on `<extension>` | `site` or `administrator` — **required for plugins and modules** |
|
|
| `<folder>` | `group` attribute on `<extension>` | Plugin group (e.g., `system`, `content`) — **required for plugins** |
|
|
| `<targetplatform>` | `<targetplatform>` in manifest | Falls back to Joomla 5.x / 6.x if not specified |
|
|
| `<php_minimum>` | `<php_minimum>` in manifest | Included only if present |
|
|
|
|
### Extension Manifest Setup
|
|
|
|
Your XML manifest must include an `<updateservers>` tag pointing to the `update.xml` on the `main` branch:
|
|
|
|
```xml
|
|
<extension type="component" client="site" method="upgrade">
|
|
<name>My Extension</name>
|
|
<element>com_myextension</element>
|
|
<!-- ... -->
|
|
<updateservers>
|
|
<server type="extension" name="My Extension Updates">
|
|
https://raw.githubusercontent.com/mokoconsulting-tech/MokoWaaS/main/update.xml
|
|
</server>
|
|
</updateservers>
|
|
</extension>
|
|
```
|
|
|
|
### Branch Lifecycle
|
|
|
|
```
|
|
dev → [alpha] → [beta] → rc → version/XX → main → dev
|
|
optional optional (integration) (production) (feedback)
|
|
```
|
|
|
|
1. **Development** (`dev` or `dev/**`): `updates.xml` with `<tag>development</tag>`, download points to Gitea release ZIP
|
|
2. **Alpha** (`alpha/**`): `updates.xml` with `<tag>alpha</tag>`, cascades to development channel
|
|
3. **Beta** (`beta/**`): `updates.xml` with `<tag>beta</tag>`, cascades to alpha + development channels
|
|
4. **Release Candidate** (`rc/**`): `updates.xml` with `<tag>rc</tag>`, cascades to beta + alpha + development channels
|
|
5. **Stable Release** (merge to `main`): `updates.xml` with `<tag>stable</tag>`, cascades to all channels, download points to GitHub Release asset
|
|
6. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed
|
|
|
|
### Health Checks
|
|
|
|
The `repo_health.yml` workflow verifies on every commit:
|
|
|
|
- `update.xml` exists in the repository root
|
|
- XML manifest exists with `<extension>` tag
|
|
- `<version>`, `<name>`, `<author>`, `<namespace>` tags present
|
|
- Extension `type` attribute is valid
|
|
- Language `.ini` files exist
|
|
- `index.html` directory listing protection in `src/`, `src/admin/`, `src/site/`
|
|
|
|
---
|
|
|
|
*Managed by [MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards). See [docs/workflows/update-server.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/workflows/update-server.md) for the full specification.*
|