fix: use highest semver tag for stable docs, not most recent

The deploy-docs workflow previously picked the release tag with the most
recent creation date. A maintenance patch on an older minor (e.g. 0.4.3
after 0.5.0) would cause stable docs to regress to that older codebase.

Switch to sorting by semver version so stable docs always reflect the
latest release line.

Author: clavery

.github/workflows/deploy-docs.yml

@@ -54,21 +54,35 @@ jobs:
       - name: Get latest release tag
         id: release
         run: |
-          # Find the most recent package tag and docs tag across all branches
-          # (git describe only finds ancestor tags; git tag --list finds all)
-          PKG_TAG=$(git tag --list '@salesforce/*' --sort=-creatordate | head -n1)
-          DOCS_TAG=$(git tag --list 'docs@*' --sort=-creatordate | head -n1)
-
-          # Pick whichever tag was created most recently
+          # Find the highest-versioned package tag and docs tag (by semver, not
+          # creation date) so that maintenance patches on older minors never
+          # cause stable docs to regress to an older codebase.
+          pick_highest() {
+            node -e "
+              const lines = require('fs').readFileSync('/dev/stdin','utf8').trim().split('\n').filter(Boolean);
+              const parsed = lines.map(tag => {
+                const ver = tag.split('@').pop();
+                const [major, minor, patch] = ver.split('.').map(Number);
+                return { tag, major, minor, patch };
+              }).filter(t => !isNaN(t.major));
+              parsed.sort((a, b) => b.major - a.major || b.minor - a.minor || b.patch - a.patch);
+              if (parsed.length) console.log(parsed[0].tag);
+            "
+          }
+
+          PKG_TAG=$(git tag --list '@salesforce/*' | pick_highest)
+          DOCS_TAG=$(git tag --list 'docs@*' | pick_highest)
+
+          # Pick whichever tag has the higher semver version
           LATEST_TAG=""
           if [[ -n "$PKG_TAG" && -n "$DOCS_TAG" ]]; then
-            PKG_TS=$(git for-each-ref --format='%(creatordate:unix)' "refs/tags/${PKG_TAG}")
-            DOCS_TS=$(git for-each-ref --format='%(creatordate:unix)' "refs/tags/${DOCS_TAG}")
-            if [[ "$DOCS_TS" -ge "$PKG_TS" ]]; then
-              LATEST_TAG="$DOCS_TAG"
-            else
-              LATEST_TAG="$PKG_TAG"
-            fi
+            WINNER=$(node -e "
+              const a = '${PKG_TAG}'.split('@').pop().split('.').map(Number);
+              const b = '${DOCS_TAG}'.split('@').pop().split('.').map(Number);
+              const cmp = a[0]-b[0] || a[1]-b[1] || a[2]-b[2];
+              console.log(cmp >= 0 ? '${PKG_TAG}' : '${DOCS_TAG}');
+            ")
+            LATEST_TAG="$WINNER"
           elif [[ -n "$PKG_TAG" ]]; then
             LATEST_TAG="$PKG_TAG"
           elif [[ -n "$DOCS_TAG" ]]; then

PUBLISHING.md

@@ -152,7 +152,7 @@ The documentation site serves two versions:
 - **Stable** (root URL) — built from the most recent release tag (across all branches)
 - **Dev** (`/dev/`) — built from `main`, updated on every push
 
-Stable docs are rebuilt after every stable or release branch publish. The `deploy-docs.yml` workflow finds the most recent release tag by creation date across all branches, so tags from release branches are picked up automatically.
+Stable docs are rebuilt after every stable or release branch publish. The `deploy-docs.yml` workflow builds from the highest semver release tag, so stable docs always reflect the latest release line. Maintenance patches on older minors do not affect stable docs.
 
 ## Local Testing