BRIEF: How update files (update.txt and updates.xml) are generated per platform
-->
# Update Server Files
MokoStandards automatically generates platform-specific update server files on every release and dev/alpha/beta/rc deployment.
## Overview
| Platform | File | Format | Reference |
|----------|------|--------|-----------|
| Dolibarr (`crm-module`) | `update.txt` | Plain text version string (< 30 chars) | Dolibarr `url_last_version` check |
| Joomla (`waas-component`) | `updates.xml` | Multi-entry XML following Joomla update server spec | [Joomla Update Server Docs](https://docs.joomla.org/Deploying_an_Update_Server) |
## Stability Tags
Joomla's `updates.xml` contains **multiple `<update>` entries simultaneously** — one per stability level. Joomla filters which entries the admin sees based on the site's **Minimum Stability** setting (Extensions > Update > Options).
| Stability | Joomla `<tag>` | Who sees it | Source workflow |
| Stable | `<tag>stable</tag>` | All sites (default) | `auto-release.yml` on `main` |
| Release Candidate | `<tag>rc</tag>` | Sites set to RC or lower | `update-server.yml` on `rc/**` push |
| Beta | `<tag>beta</tag>` | Sites set to Beta or lower | `update-server.yml` on `beta/**` push |
| Alpha | `<tag>alpha</tag>` | Sites set to Alpha or lower | `update-server.yml` on `alpha/**` push |
| Development | `<tag>development</tag>` | Sites set to Development | `update-server.yml` on `dev/**` push |
**Note**: Alpha and beta are optional stages. Not every release cycle will have alpha/beta entries.
### How Joomla Filters Updates
Joomla's update system reads all `<update>` entries from the XML file but only presents entries whose `<tag>` matches the site's minimum stability threshold:
- **Minimum Stability = Stable** (default): Only sees `<tag>stable</tag>` entries
- **Minimum Stability = RC**: Sees `stable` + `rc` entries
- **`dev/**`**: Active development. Update files tagged as `development`.
- **`alpha/**`**: *(Optional)* Early internal testing. Update files tagged as `alpha`. Can be skipped.
- **`beta/**`**: *(Optional)* Broader external testing. Update files tagged as `beta`. Can be skipped.
- **`rc/**`**: Release candidate. Update files tagged as `rc`. RC branches deploy to dev server for final testing.
- **`version/XX`**: Major version integration branch (major only). All minors and patches flow into the same major branch.
- **`main`**: Stable release. `auto-release.yml` creates GitHub Release and `vXX` tag. Update files tagged as `stable`.
- **Main merges back to `dev`** to start the next cycle.
## Dolibarr: `update.txt`
Dolibarr modules check for updates by fetching a plain-text file from the URL in `$this->url_last_version`. The file must contain only the version string (e.g., `01.02.03`) — no JSON, no XML, no newlines.
**On release (main):**
```
01.02.03
```
**On RC deploy (rc/**):**
```
01.02.03-rc
```
**On dev deploy (dev/**):**
```
development
```
The module descriptor's `url_last_version` should point to:
The `updates.xml` file contains **up to five stability entries at once** (one per stability level). Joomla reads the entire file and filters by the site's minimum stability setting.
| `auto-release.yml` | Push to `main` | `<tag>stable</tag>` — writes the stable entry with SHA-256 hash of the ZIP |
| `update-server.yml` | Push to `rc/**` | `<tag>rc</tag>` — adds/updates the RC entry |
| `update-server.yml` | Push to `beta/**` | `<tag>beta</tag>` — adds/updates the beta entry |
| `update-server.yml` | Push to `alpha/**` | `<tag>alpha</tag>` — adds/updates the alpha entry |
| `update-server.yml` | Push to `dev/**` | `<tag>development</tag>` — adds/updates the development entry |
The `auto-release.yml` workflow writes the stable entry and preserves any existing pre-release entries. The `update-server.yml` workflow writes only its specific entry (rc, beta, alpha, or dev) and preserves the others.
### XML Elements
All metadata is auto-extracted from the extension's XML manifest at build time:
| Element | Source | Notes |
|---------|--------|-------|
| `<name>` | `<name>` in manifest | Extension display name |
| `<element>` | `<element>` in manifest, or manifest filename | Must match installed extension |
The `<updateservers>` tag tells Joomla where to check for updates. Both servers are declared for redundancy — Gitea (primary, priority 1) and GitHub mirror (fallback, priority 2).
## How It Works
### Joomla (updates.xml)
1.**On release** (`auto-release.yml` → main branch):
- Builds ZIP from `src/` directory
- Uploads ZIP to the `vXX` major release on GitHub
- Computes SHA-256 hash of the ZIP
- Writes/updates the `<tag>stable</tag>` entry in `updates.xml` with version, download URL, and SHA-256
- Preserves any existing rc/dev entries in the file
