Merge pull request 'feat(cli): add changelogurl and version cascade docs' (#209) from dev into main

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
     );
 }