MokoWaaS/docs/update-server.md

<!--
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.34.39
BRIEF: How this extension's Joomla update server file (update.xml) is managed
-->

# Joomla Update Server

[![MokoStandards](https://img.shields.io/badge/MokoStandards-02.01.08-blue)](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 (`source/*.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 `source/`, `source/admin/`, `source/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.*