From c3a3ab3f62492bd97b8af3fe8e6342552aa0dada Mon Sep 17 00:00:00 2001 From: Jonathan Miller <1+jmiller@noreply.git.mokoconsulting.tech> Date: Thu, 4 Jun 2026 15:38:29 +0000 Subject: [PATCH] docs: add Joomla Update Server standards [skip ci] --- .../required/template-update-server-joomla.md | 168 +++++++----------- 1 file changed, 68 insertions(+), 100 deletions(-) diff --git a/templates/docs/required/template-update-server-joomla.md b/templates/docs/required/template-update-server-joomla.md index ae66059..d47dc93 100644 --- a/templates/docs/required/template-update-server-joomla.md +++ b/templates/docs/required/template-update-server-joomla.md @@ -1,122 +1,90 @@ - - -# 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 `` 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 | `` | `` | -|-------|----------|---------|-------------| -| 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 - - - - Extension Name - Extension Name update - com_extensionname - component - 01.02.03 - site - system - - stable - - - https://git.mokoconsulting.tech/.../releases/download/v01.02.03/com_ext-01.02.03.zip - https://github.com/.../releases/download/v01.02.03/com_ext-01.02.03.zip - - - 8.2 - Moko Consulting - https://mokoconsulting.tech - - + + + https://git.mokoconsulting.tech/MokoConsulting/{RepoName}/updates.xml + + ``` -### Metadata Source +## Release Naming Convention -All metadata is extracted from the extension's XML manifest (`src/*.xml`) at build time: - -| XML Element | Source | Notes | -|-------------|--------|-------| -| `` | `` in manifest | Extension display name | -| `` | `` in manifest | Must match installed extension identifier | -| `` | `type` attribute on `` | `component`, `module`, `plugin`, `library`, `package`, `template` | -| `` | `client` attribute on `` | `site` or `administrator` — **required for plugins and modules** | -| `` | `group` attribute on `` | Plugin group (e.g., `system`, `content`) — **required for plugins** | -| `` | `` in manifest | Falls back to Joomla 5.x / 6.x if not specified | -| `` | `` in manifest | Included only if present | - -### Extension Manifest Setup - -Your XML manifest must include an `` tag pointing to the `updates.xml` on the `main` branch: - -```xml - - My Extension - com_myextension - - - - https://git.mokoconsulting.tech/mokoconsulting-tech/{{REPO_NAME}}/raw/branch/main/updates.xml - - - https://raw.githubusercontent.com/mokoconsulting-tech/{{REPO_NAME}}/main/updates.xml - - - -``` - -### 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 `development`, download points to branch archive -2. **Release Candidate** (`rc/**`): `updates.xml` with `rc`, version set to `XX.YY.ZZ-rc` -3. **Stable Release** (merge to `main`): `updates.xml` with `stable`, 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 `` tag -- ``, ``, ``, `` 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).