1

Update-Server-Migration-Protocol

Jonathan Miller edited this page 2026-06-04 14:38:24 +00:00

Table of Contents

• Update Server Migration Protocol
• Overview
• How Joomla Update Discovery Works
• Migration Protocol
• Step 1: Verify new URL is accessible
• Step 2: Confirm old URL still works
• Step 3: Update manifest XML
• Step 4: Release the extension
• Step 5: Deprecation (optional, after 90+ days)
• Technical Details
• Release Workflow Changes
• Database Impact
• Verification Checklist
• Migration Status
• Rollback

Update Server Migration Protocol

Overview

Joomla extensions in the MokoConsulting ecosystem are migrating their update server URLs from the raw file endpoint to the Gitea Pages endpoint.

	Old Pattern	New Pattern
URL	/{REPO}/raw/branch/main/updates.xml	/{REPO}/updates.xml
Content-Type	text/plain	application/xml
Depends on	Git branch structure	Gitea Pages

Why: The new URL is cleaner, serves the correct application/xml content type (important for some Joomla versions), and decouples the update stream from the git branch structure. Release workflows no longer manage updates.xml directly -- it is managed by the Gitea Pages licensing system.

---

How Joomla Update Discovery Works

1. Each extension's manifest XML (e.g. templateDetails.xml) contains an <updateservers> block with the URL where Joomla should check for updates
2. When the extension is installed or updated, Joomla stores this URL in the #__update_sites database table
3. Joomla periodically fetches updates.xml from that URL to check for new versions
4. The URL only changes when a new version is installed that contains an updated manifest -- existing installs keep using the cached URL until they update

This means the old URL must keep working until all installs have received at least one update with the new URL in the manifest.

---

Migration Protocol

Step 1: Verify new URL is accessible

curl -sI "https://git.mokoconsulting.tech/MokoConsulting/{REPO}/updates.xml"
# Expected: HTTP 200, Content-Type: application/xml

Step 2: Confirm old URL still works

curl -sI "https://git.mokoconsulting.tech/MokoConsulting/{REPO}/raw/branch/main/updates.xml"
# Expected: HTTP 200 (backwards compatible)

Both URLs serve the same updates.xml content. Gitea serves both by default -- no additional configuration needed.

Step 3: Update manifest XML

Change the <updateservers> URL in the extension's manifest file:

<!-- Before -->
<server type="extension" name="...">
    https://git.mokoconsulting.tech/MokoConsulting/{REPO}/raw/branch/main/updates.xml
</server>

<!-- After -->
<server type="extension" name="...">
    https://git.mokoconsulting.tech/MokoConsulting/{REPO}/updates.xml
</server>

Update on both dev and main branches.

Step 4: Release the extension

Release a new version. Installs that update will receive the new manifest, and Joomla will update the cached URL in #__update_sites.

Step 5: Deprecation (optional, after 90+ days)

After sufficient adoption, the old URL can be deprecated. However, Gitea will continue serving /raw/branch/main/updates.xml as long as the file exists in the repo, so no action is strictly needed.

---

Technical Details

Release Workflow Changes

• release_publish.php now supports --skip-update-stream flag
• When passed, Steps 5 (updates.xml build) and 6 (updates.xml commit/sync) are skipped
• auto-release.yml across all repos passes this flag in both promote-rc and release jobs
• updates.xml is now managed externally by the Gitea Pages licensing system

Database Impact

Existing Joomla installs have the old URL stored in:

SELECT * FROM #__update_sites WHERE location LIKE '%/raw/branch/main/updates.xml';

After updating to a version with the new manifest, this becomes:

SELECT * FROM #__update_sites WHERE location LIKE '%/updates.xml' AND location NOT LIKE '%/raw/%';

No manual database changes are needed -- Joomla handles this automatically on extension update.

---

Verification Checklist

• New URL returns HTTP 200 with Content-Type: application/xml
• Old URL still returns HTTP 200 (backwards compatible)
• Manifest XML updated with new URL on both dev and main
• Release published with updated manifest
• Joomla test site picks up update from new URL
• auto-release.yml has --skip-update-stream flag

---

Migration Status

Repo	Manifest File	Status	Version	Date
MokoOnyx	src/templateDetails.xml	Migrated	02.20.00	2026-06-04
MokoJoomHero	src/pkg_mokojoomhero.xml	Migrated	--	2026-06-04
MokoJoomTOS	src/mokojoomtos.xml	Migrated	--	2026-06-04
MokoJoomStoreLocator	src/pkg_mokojoomstorelocator.xml	Migrated	--	2026-06-04
MokoJoomOpenGraph	src/pkg_mokoog.xml	Migrated	--	2026-06-04
MokoJoomCross	src/pkg_mokojoomcross.xml	Migrated	--	2026-06-04
MokoJoomBackup	src/pkg_mokobackup.xml	Migrated	--	2026-06-04
MokoGalleryCalendar	src/mokojgdpc.xml	Migrated	--	2026-06-04
MokoDPCalendarAPI	src/mokodpcalendarapi.xml	Migrated	--	2026-06-04
MokoDoliJoomShop	src/mokodolijoomshop.xml	Migrated	--	2026-06-04

---

Rollback

If something breaks:

1. Old URL continues to work -- no action needed for existing installs
2. Revert manifest XML to old URL pattern on dev and main
3. Release a patch version with the reverted manifest
4. The --skip-update-stream flag can be removed from auto-release.yml if needed to restore the old updates.xml management behavior