Universal Update Server Standard

Canonical reference for the update server architecture across all Moko Consulting repositories.

Overview

All Moko Consulting repositories use a universal update server pattern based on the Joomla update XML format. This provides a consistent way to track versions, stability channels, and download URLs across all platforms (Joomla, Dolibarr, generic, MCP, Node.js).

The .mokogitea/manifest.xml file in each repository determines how the update server data is interpreted for that platform.

Architecture

Template-Generic (source of truth)
    └── update-server.yml (universal workflow)
         ├── Template-Joomla
         ├── Template-Dolibarr
         ├── Template-Client-WaaS
         └── All governed repos (69+)

Flow

Feature merge to dev → pre-release.yml builds a development pre-release
Pre-release builds → update-server.yml updates updates.xml with version, download URL, and channel tag
Draft PR to main → auto-release.yml promotes pre-release to RC
PR merge to main → auto-release.yml promotes RC to stable (or full build if no RC)
Stable release → update-server.yml updates stable channel, cascades lesser channels

updates.xml Format

The updates.xml file is the update manifest. Each <update> block represents a stability channel.

<?xml version="1.0" encoding="utf-8"?>
<updates>
  <update>
    <name>Extension Name</name>
    <description>Stable release</description>
    <element>ext_element</element>
    <type>package</type>
    <version>09.01.00</version>
    <tag>stable</tag>
    <downloads>
      <downloadurl type="full" format="zip">
        https://git.mokoconsulting.tech/Org/Repo/releases/download/stable/pkg_element-09.01.00.zip
      </downloadurl>
    </downloads>
    <targetplatform name="joomla" version="5.[0-9]" />
    <client>site</client>
  </update>

  <update>
    <name>Extension Name</name>
    <description>Development build</description>
    <element>ext_element</element>
    <type>package</type>
    <version>09.01.01</version>
    <tag>development</tag>
    <downloads>
      <downloadurl type="full" format="zip">
        https://git.mokoconsulting.tech/Org/Repo/releases/download/development/element-09.01.01-dev.zip
      </downloadurl>
    </downloads>
    <targetplatform name="joomla" version="5.[0-9]" />
    <client>site</client>
  </update>
</updates>

Stability Channels

Channel	Tag	Suffix	Trigger
Stable	`stable`	(none)	PR merge to main
Release Candidate	`release-candidate`	`-rc`	Draft PR to main
Beta	`beta`	`-beta`	Manual dispatch
Alpha	`alpha`	`-alpha`	Manual dispatch
Development	`development`	`-dev`	Feature merge to dev

Cascade Rules

When a higher channel is published, all lesser channels are deleted:

Published	Deletes
stable	development, alpha, beta, release-candidate
release-candidate	development, alpha, beta
beta	development, alpha
alpha	development

Additionally, any release on any channel with a lesser version number than the published version is deleted (version-aware cascade).

Platform Interpretation

The .mokogitea/manifest.xml file determines platform-specific behavior:

Platform	`<platform>` value	Update mechanism
Joomla	`joomla`, `waas-component`	Native Joomla update XML — `updates.xml` served via Gitea release assets
Dolibarr	`dolibarr`, `crm-module`	`update.txt` version file + `updates.xml` for channel tracking
Generic	`generic`	`updates.xml` for version tracking and download URLs
MCP	`mcp`, `nodejs`	`updates.xml` for version tracking

CLI Tools

Tool	Purpose
`updates_xml_build.php`	Build/update `updates.xml` with version, channel, download URL
`release_package.php`	Build ZIP/tar.gz packages, upload to Gitea release
`release_create.php`	Create/overwrite Gitea release with proper naming
`release_promote.php`	Promote releases between channels (dev→RC→stable)
`release_cascade.php`	Delete lesser channels + version-aware cleanup
`release_mirror.php`	Mirror Gitea release to GitHub
`manifest_element.php`	Extract element/type/prefix from manifest
`release_validate.php`	Pre-release validation (version drift, required files)

Workflow Files

Workflow	Source of Truth	Purpose
`auto-release.yml`	Template-Generic	Build & release on PR merge to main
`pre-release.yml`	Template-Generic	Dev/alpha/beta/RC pre-releases
`update-server.yml`	Template-Generic	Update server management

Version Format

All versions use zero-padded two-digit segments: XX.YY.ZZ

Major (XX): Breaking changes
Minor (YY): New features (bumped on stable release)
Patch (ZZ): Bug fixes (bumped on pre-release)

Example: 09.01.00 → major 9, minor 1, patch 0

WORKFLOW_STANDARDS — CI/CD workflow conventions
MANIFEST-STANDARD — manifest.xml schema
Branching-Strategy — Branch naming and merge flow