MokoWaaS/docs/update-server.md

Joomla Update Server

This document explains how update.xml is automatically managed for this Joomla extension following the Joomla Update Server specification.

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 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:

<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. See docs/workflows/update-server.md for the full specification.