From dea7557e42e48674bea33132c5cf68130520f7dd Mon Sep 17 00:00:00 2001
From: Chris Wolfgang <210299580+Chris-Wolfgang@users.noreply.github.com>
Date: Sat, 18 Jul 2026 08:19:12 -0400
Subject: [PATCH 1/2] fix(docs): surface 'latest' alias only on
 /versions/latest/
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The version picker defaulted currentVersion to 'latest', so on the site
root and every unversioned page it surfaced AND selected the 'latest'
option — not just on /versions/latest/. Default to null instead: only a
/versions/<v>/ path (including the literal /versions/latest/) names a
version; elsewhere 'latest' stays hidden and the browser auto-selects the
highest v* entry.

Fed back from Chris-Wolfgang/ETL-Abstractions#268.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docfx_project/public/version-picker.js | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/docfx_project/public/version-picker.js b/docfx_project/public/version-picker.js
index f155c73b..2f601ee2 100644
--- a/docfx_project/public/version-picker.js
+++ b/docfx_project/public/version-picker.js
@@ -49,8 +49,14 @@
     }
 
     function renderPicker(versions) {
-        // Detect the currently-viewed version from the URL.
-        var currentVersion = 'latest';
+        // Detect the currently-viewed version from the URL. Only a
+        // /versions/<v>/ path names a concrete version; the literal
+        // /versions/latest/ alias yields 'latest'. Anywhere else (site
+        // root, unversioned pages) currentVersion stays null so the
+        // 'latest' alias is NOT surfaced and the browser auto-selects the
+        // highest v* entry — matching the intent that 'latest' appears in
+        // the picker only on /versions/latest/.
+        var currentVersion = null;
         var m = window.location.pathname.match(/\/versions\/([^\/]+)(?:\/|$)/);
         if (m) {
             currentVersion = m[1];
@@ -86,12 +92,16 @@
         var optionCount = 0;
         versions.forEach(function (v) {
             if (!v || !v.version || !v.url) return;
-            // Skip the "latest" alias — the highest-numbered v* entry
-            // already represents the latest release; surfacing both is
-            // redundant in the picker. versions.json keeps the "latest"
-            // entry so other consumers (links, scripts) can still
+            // Skip the "latest" alias EXCEPT when the reader is actually
+            // on /versions/latest/. On every other page the highest-
+            // numbered v* entry already represents the latest release and
+            // surfacing both is redundant; on /versions/latest/ we NEED
+            // 'latest' in the list because otherwise the picker would show
+            // no selected option and the reader would have no way to know
+            // which version they are viewing. versions.json keeps the
+            // "latest" entry so other consumers (links, scripts) can still
             // resolve it.
-            if (v.version === 'latest') return;
+            if (v.version === 'latest' && currentVersion !== 'latest') return;
             var opt = document.createElement('option');
             opt.value = v.url;
             opt.textContent = v.version;

From 0efa8c50739c1e78634d7bb5385057835fb44e8e Mon Sep 17 00:00:00 2001
From: Chris Wolfgang <210299580+Chris-Wolfgang@users.noreply.github.com>
Date: Fri, 24 Jul 2026 16:22:59 -0400
Subject: [PATCH 2/2] docs(version-picker): correct comment about auto-select
 behavior
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Copilot review on downstream syncs (DbContextBuilder#369, System.Mail-
Extensions#208) flagged the "would show no selected option" claim as
inaccurate — browsers auto-select the first option in a `<select>`.
The real problem is that the auto-selected first concrete-version
entry matches the current URL, so choosing it doesn't fire `change`
and the reader can't navigate to the concrete-version URL.

Fixed in the downstreams already (93780ed, 15f175f); propagating back
to the canonical source so future template-syncs carry the accurate
rationale.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docfx_project/public/version-picker.js | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/docfx_project/public/version-picker.js b/docfx_project/public/version-picker.js
index 2f601ee2..647d71db 100644
--- a/docfx_project/public/version-picker.js
+++ b/docfx_project/public/version-picker.js
@@ -96,10 +96,12 @@
             // on /versions/latest/. On every other page the highest-
             // numbered v* entry already represents the latest release and
             // surfacing both is redundant; on /versions/latest/ we NEED
-            // 'latest' in the list because otherwise the picker would show
-            // no selected option and the reader would have no way to know
-            // which version they are viewing. versions.json keeps the
-            // "latest" entry so other consumers (links, scripts) can still
+            // 'latest' in the list because without it the browser auto-
+            // selects the first concrete version (whichever v* is top of
+            // the list), and choosing that same value doesn't fire
+            // `change`, so the reader can't navigate away to the
+            // concrete-version URL. versions.json keeps the "latest"
+            // entry so other consumers (links, scripts) can still
             // resolve it.
             if (v.version === 'latest' && currentVersion !== 'latest') return;
             var opt = document.createElement('option');