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

docs: add Joomla Update Server standards [skip ci]

Browse Source
This commit is contained in:
Jonathan Miller
2026-06-04 15:38:29 +00:00
parent 556ac85a63
commit c3a3ab3f62
1 changed files with 68 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files
templates/docs/required/template-update-server-joomla.md
+68 -100
View File
@@ -1,122 +1,90 @@
<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
# Update Server — Joomla Extensions
This file is part of a Moko Consulting project.
## Overview
SPDX-License-Identifier: GPL-3.0-or-later
# FILE INFORMATION
DEFGROUP: {{REPO_NAME}}.Documentation
INGROUP: MokoPlatform.Templates
REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/{{REPO_NAME}}
PATH: /docs/update-server.md
VERSION: {{standards_version}}
BRIEF: How this extension's Joomla update server file (updates.xml) is managed
-->
# Joomla Update Server
[![moko-platform](https://img.shields.io/badge/moko--platform-{{standards_version}}-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform)
This document explains how `updates.xml` is automatically managed for this Joomla extension following the [Joomla Update Server specification](https://docs.joomla.org/Deploying_an_Update_Server).
MokoGitea provides a built-in Update Server that dynamically generates Joomla-compatible update XML feeds from repository releases. **No static `updates.xml` file is needed in the repository.**
## 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. moko-platform generates this file automatically.
1. **Enable Update Server** in the repository's Settings > Advanced Settings
2. **Configure metadata** in Settings > Update Server (extension name, type, target version, etc.)
3. **Create releases** with tagged assets (e.g. `pkg_mokowaas-02.19.00.zip`)
4. MokoGitea automatically serves the update feed at `/{owner}/{repo}/updates.xml`
### Automatic Generation
## Feed URL
| Event | Workflow | `<tag>` | `<version>` |
|-------|----------|---------|-------------|
| Merge to `main` | `auto-release.yml` | `stable` | `XX.YY.ZZ` |
| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` |
| Push to `rc/**` | `deploy-dev.yml` | `rc` | `XX.YY.ZZ-rc` |
```
https://git.mokoconsulting.tech/{owner}/{repo}/updates.xml
```
### Generated XML Structure
This URL is what goes into your Joomla extension's `update_server` element in the manifest XML.
## Manifest Configuration
In your extension's manifest XML (`*.xml`), add:
```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>
<downloads>
<downloadurl type="full" format="zip">https://git.mokoconsulting.tech/.../releases/download/v01.02.03/com_ext-01.02.03.zip</downloadurl>
<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>
<updateservers>
<server type="extension" name="{Extension Name}">
https://git.mokoconsulting.tech/MokoConsulting/{RepoName}/updates.xml
</server>
</updateservers>
```
### Metadata Source
## Release Naming Convention
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 `updates.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" priority="1" name="My Extension Update Server (Gitea)">
https://git.mokoconsulting.tech/mokoconsulting-tech/{{REPO_NAME}}/raw/branch/main/updates.xml
</server>
<server type="extension" priority="2" name="My Extension Update Server (GitHub)">
https://raw.githubusercontent.com/mokoconsulting-tech/{{REPO_NAME}}/main/updates.xml
</server>
</updateservers>
</extension>
```
### Branch Lifecycle
Release assets must follow this naming pattern for the feed generator to detect them:
```
dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX
(development) (rc) (stable) (frozen snapshot)
{extension_name}-{version}.zip
{extension_name}-{version}.tar.gz
```
1. **Development** (`dev/**`): `updates.xml` with `<tag>development</tag>`, download points to branch archive
2. **Release Candidate** (`rc/**`): `updates.xml` with `<tag>rc</tag>`, version set to `XX.YY.ZZ-rc`
3. **Stable Release** (merge to `main`): `updates.xml` with `<tag>stable</tag>`, download points to Gitea Release asset (primary) + GitHub Release asset (mirror)
4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed
Examples:
- `pkg_mokowaas-02.19.00.zip`
- `tpl_mokoonyx-02.19.00.zip`
- `mod_mokojoomhero-01.05.00.zip`
### Health Checks
## Update Server Settings
The `repo_health.yml` workflow verifies on every commit:
Configure these in Settings > Update Server:
- `updates.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/`
| Field | Description | Example |
|-------|-------------|---------|
| Extension Name | Joomla element name | `pkg_mokowaas` |
| Display Name | Human-readable name | `Package - MokoWaaS` |
| Extension Type | package, plugin, template, module, component | `package` |
| Target Version | Regex for compatible Joomla versions | `(5|6)\..*` |
| PHP Minimum | Minimum PHP version | `8.1` |
| Maintainer | Organization name | `Moko Consulting` |
| Maintainer URL | Organization website | `https://mokoconsulting.tech` |
| Support URL | Product support page | `https://mokoconsulting.tech/products/{alias}` |
| Info URL | Product information page | `https://mokoconsulting.tech/products/{alias}` |
---
## Download Gating
*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.*
Three modes control who can download release assets:
| Mode | Behavior |
|------|----------|
| `none` | All downloads are public |
| `prerelease` | Pre-release downloads require a license key; stable releases are public |
| `all` | All downloads require a license key |
The update feed XML is **always public** — only the actual file downloads are gated.
## What NOT to Do
- **Do NOT commit `updates.xml` to the repository** — it is served dynamically
- **Do NOT use static update server workflows** — the old CI-generated approach is deprecated
- **Do NOT hardcode version numbers in feed URLs** — the feed auto-detects from releases
## Changelog Feed
A changelog XML is also served automatically at:
```
https://git.mokoconsulting.tech/{owner}/{repo}/changelog.xml
```
This is generated from release notes (markdown body of each release).