From 56deb8b9235e64a49699a51da66b42e64a130da5 Mon Sep 17 00:00:00 2001
From: Jonathan Miller <jmiller-moko@noreply.git.mokoconsulting.tech>
Date: Fri, 29 May 2026 05:50:59 -0500
Subject: [PATCH] feat(cli): add changelogurl support to updates_xml_build

- Add <changelogurl> tag to all update entries (Joomla best practice)
- Points to CHANGELOG.md on main branch
- Add comment clarifying version cascading behaviour

Authored-by: Moko Consulting
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 cli/updates_xml_build.php | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/cli/updates_xml_build.php b/cli/updates_xml_build.php
index c7b3435..d90ab57 100644
--- a/cli/updates_xml_build.php
+++ b/cli/updates_xml_build.php
@@ -367,7 +367,8 @@ function buildEntry(
     string $infoUrl,
     string $targetPlatform,
     string $phpTag,
-    string $shaTag
+    string $shaTag,
+    string $changelogUrl = ''
 ): string {
     $lines = [];
     $lines[] = '  <update>';
@@ -399,6 +400,9 @@ function buildEntry(
         $lines[] = $shaTag;
     }
     $lines[] = "    <tags><tag>{$tagName}</tag></tags>";
+    if (!empty($changelogUrl)) {
+        $lines[] = "    <changelogurl>{$changelogUrl}</changelogurl>";
+    }
     $lines[] = '    <maintainer>Moko Consulting</maintainer>';
     $lines[] = '    <maintainerurl>https://mokoconsulting.tech</maintainerurl>';
     $lines[] = "    {$targetPlatform}";
@@ -443,9 +447,15 @@ for ($i = 0; $i <= $stabilityIndex; $i++) {
     $joomlaTag = $stabilityTagMap[$channelName] ?? $channelName;
     $stabilityLabel = $stabilityLabelMap[$channelName] ?? $channelName;
 
+    // All cascaded entries use the SAME version as the highest-stability package.
+    // The version MUST match what's inside the ZIP (Joomla reads it post-install).
+    // The <tag> differentiates channels; the version is always the release version.
+    // Changelog URL: points to the CHANGELOG.md on main branch
+    $changelogUrl = "{$giteaUrl}/{$org}/{$repo}/raw/branch/main/CHANGELOG.md";
+
     $entries[] = buildEntry(
         $joomlaTag,
-        $channelVersion,
+        $entryVersion,
         $channelDownloadUrl,
         $displayName,
         $stabilityLabel,
@@ -456,7 +466,8 @@ for ($i = 0; $i <= $stabilityIndex; $i++) {
         $channelInfoUrl,
         $targetPlatform,
         $phpTag,
-        $shaTag
+        $shaTag,
+        $changelogUrl
     );
 }