From 9719f1c0b7efdb6ea784395d2c9b13cdf80095c1 Mon Sep 17 00:00:00 2001
From: Simon Legner <Simon.Legner@gmail.com>
Date: Mon, 14 Sep 2026 09:28:22 +0200
Subject: [PATCH 1/4] Add a preference to use the latest version of a
 documentation

Enabling it replaces, at boot, every enabled doc for which a newer version
is available with that version, so that e.g. CMake 3.9 becomes CMake 3.12
once it is released.

Only numbered versions are migrated; variants that share a name, such as
Node.js 10 LTS or the Haxe targets, can't be ordered and are left alone.
An empty version means the doc holds the latest version and outranks any
number. saveDocs bumps the database schema, which drops the object store
of the superseded doc just like disabling it manually does.

Closes #744
---
 assets/javascripts/app/app.js                 |  31 ++++
 assets/javascripts/app/settings.js            |   2 +
 assets/javascripts/models/doc.js              |  49 ++++++
 .../templates/pages/settings_tmpl.js          |   6 +
 .../views/content/settings_page.js            |   1 +
 test/assets/doc_version_test.js               | 142 ++++++++++++++++++
 6 files changed, 231 insertions(+)
 create mode 100644 test/assets/doc_version_test.js

diff --git a/assets/javascripts/app/app.js b/assets/javascripts/app/app.js
index 3ced2c403c..fc063b821d 100644
--- a/assets/javascripts/app/app.js
+++ b/assets/javascripts/app/app.js
@@ -123,6 +123,7 @@ class App extends Events {
       (docs.includes(doc.slug) ? this.docs : this.disabledDocs).add(doc);
     }
     this.migrateDocs();
+    this.migrateToLatestVersions();
     this.docs.load(this.start.bind(this), this.onBootError.bind(this), {
       readCache: true,
       writeCache: true,
@@ -190,6 +191,36 @@ class App extends Events {
     }
   }
 
+  // With the "latest version" preference enabled, replace the enabled docs for
+  // which a newer version is available with that version.
+  migrateToLatestVersions() {
+    if (!this.settings.get("autoLatestVersion")) {
+      return;
+    }
+
+    let needsSaving;
+    const allDocs = this.docs.all().concat(this.disabledDocs.all());
+
+    for (var doc of this.docs.all().slice()) {
+      var latest = doc.findLatestVersion(allDocs);
+      if (latest === doc) {
+        continue;
+      }
+      this.docs.remove(doc);
+      this.disabledDocs.add(doc);
+      if (!this.docs.contains(latest)) {
+        this.disabledDocs.remove(latest);
+        this.docs.add(latest);
+      }
+      needsSaving = true;
+    }
+
+    if (needsSaving) {
+      this.docs.sort();
+      this.saveDocs();
+    }
+  }
+
   enableDoc(doc, _onSuccess, onError) {
     if (this.docs.contains(doc)) {
       return;
diff --git a/assets/javascripts/app/settings.js b/assets/javascripts/app/settings.js
index 617830ecc9..113005a65d 100644
--- a/assets/javascripts/app/settings.js
+++ b/assets/javascripts/app/settings.js
@@ -14,6 +14,7 @@ app.Settings = class Settings {
     "tips",
     "noAutofocus",
     "autoInstall",
+    "autoLatestVersion",
     "spaceScroll",
     "spaceTimeout",
     "noDocSpecificIcon",
@@ -40,6 +41,7 @@ app.Settings = class Settings {
     spaceScroll: 1,
     spaceTimeout: 0.5,
     noDocSpecificIcon: false,
+    autoLatestVersion: false,
   };
 
   constructor() {
diff --git a/assets/javascripts/models/doc.js b/assets/javascripts/models/doc.js
index 0a5c815a85..990c4046df 100644
--- a/assets/javascripts/models/doc.js
+++ b/assets/javascripts/models/doc.js
@@ -1,6 +1,8 @@
 app.models.Doc = class Doc extends app.Model {
   // Attributes: name, slug, type, version, release, db_size, mtime, links
 
+  static NUMBERED_VERSION_RGX = /^\d+(\.\d+)*$/;
+
   constructor() {
     super(...arguments);
     this.reset(this);
@@ -192,6 +194,53 @@ app.models.Doc = class Doc extends app.Model {
     );
   }
 
+  // Whether the doc holds a numbered version of its documentation (e.g. "3.9"),
+  // as opposed to a variant (e.g. "10 LTS" or "Python"), which can't be
+  // ordered. An empty version means the doc holds the latest version
+  // (e.g. `angular`), whereas docs without a version aren't versioned at all.
+  hasNumberedVersion() {
+    return (
+      this.version === "" || Doc.NUMBERED_VERSION_RGX.test(this.version || "")
+    );
+  }
+
+  // Compares numbered versions (e.g. "3.9" is older than "3.12").
+  // An empty version means the latest version and is newer than any other.
+  isNewerVersionThan(other) {
+    if (this.version === "" || other.version === "") {
+      return this.version === "" && other.version !== "";
+    }
+    const version = this.version.split(".");
+    const otherVersion = other.version.split(".");
+    for (let i = 0; i < Math.max(version.length, otherVersion.length); i++) {
+      const diff =
+        (parseInt(version[i], 10) || 0) - (parseInt(otherVersion[i], 10) || 0);
+      if (diff !== 0) {
+        return diff > 0;
+      }
+    }
+    return false;
+  }
+
+  // Returns the doc holding the latest version of the same documentation among
+  // `docs`, or the doc itself when there is none.
+  findLatestVersion(docs) {
+    let latest = this;
+    if (!this.hasNumberedVersion()) {
+      return latest;
+    }
+    for (var doc of docs) {
+      if (
+        doc.name === this.name &&
+        doc.hasNumberedVersion() &&
+        doc.isNewerVersionThan(latest)
+      ) {
+        latest = doc;
+      }
+    }
+    return latest;
+  }
+
   isOutdated(status) {
     if (!status) {
       return false;
diff --git a/assets/javascripts/templates/pages/settings_tmpl.js b/assets/javascripts/templates/pages/settings_tmpl.js
index cfd30de1b2..f0f84bfa19 100644
--- a/assets/javascripts/templates/pages/settings_tmpl.js
+++ b/assets/javascripts/templates/pages/settings_tmpl.js
@@ -60,6 +60,12 @@ app.templates.settingsPage = (settings) => `\
       }>Automatically download documentation for offline use
       <small>Only enable this when bandwidth isn't a concern to you.</small>
     </label>
+    <label class="_settings-label">
+      <input type="checkbox" form="settings" name="autoLatestVersion" value="_auto-latest-version"${
+        settings.autoLatestVersion ? " checked" : ""
+      }>Automatically switch to the latest version of a documentation
+      <small>With this checked, enabling e.g. CMake 3.9 switches to CMake 3.10 once it becomes available.</small>
+    </label>
     <label class="_settings-label _hide-in-development">
       <input type="checkbox" form="settings" name="analyticsConsent"${
         settings.analyticsConsent ? " checked" : ""
diff --git a/assets/javascripts/views/content/settings_page.js b/assets/javascripts/views/content/settings_page.js
index d8cee94889..fa68fecd90 100644
--- a/assets/javascripts/views/content/settings_page.js
+++ b/assets/javascripts/views/content/settings_page.js
@@ -17,6 +17,7 @@ app.views.SettingsPage = class SettingsPage extends app.View {
     settings.arrowScroll = app.settings.get("arrowScroll");
     settings.noAutofocus = app.settings.get("noAutofocus");
     settings.autoInstall = app.settings.get("autoInstall");
+    settings.autoLatestVersion = app.settings.get("autoLatestVersion");
     settings.analyticsConsent = app.settings.get("analyticsConsent");
     settings.spaceScroll = app.settings.get("spaceScroll");
     settings.spaceTimeout = app.settings.get("spaceTimeout");
diff --git a/test/assets/doc_version_test.js b/test/assets/doc_version_test.js
new file mode 100644
index 0000000000..527c52fbdf
--- /dev/null
+++ b/test/assets/doc_version_test.js
@@ -0,0 +1,142 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const test = require("node:test");
+const vm = require("node:vm");
+
+const context = {
+  $: {},
+  $$: {},
+  page: {},
+  window: { matchMedia: () => ({ media: "not all" }) },
+};
+
+vm.createContext(context);
+
+// The files are concatenated because top-level class declarations aren't
+// shared between scripts run in the same context.
+vm.runInContext(
+  [
+    "assets/javascripts/lib/events.js",
+    "assets/javascripts/app/app.js",
+    "assets/javascripts/models/model.js",
+    "assets/javascripts/models/doc.js",
+    "assets/javascripts/collections/collection.js",
+    "assets/javascripts/collections/docs.js",
+  ]
+    .map((file) => fs.readFileSync(file, "utf8"))
+    .join("\n"),
+  context,
+  { filename: "devdocs.js" },
+);
+
+const { app } = context;
+
+app.collections.Entries = class Entries {
+  each() {}
+};
+app.collections.Types = class Types {
+  each() {}
+};
+app.models.Entry = class Entry {
+  addAlias() {}
+};
+
+const CMAKE = [
+  { name: "CMake", slug: "cmake~3.12", version: "3.12" },
+  { name: "CMake", slug: "cmake~3.10", version: "3.10" },
+  { name: "CMake", slug: "cmake~3.9", version: "3.9" },
+];
+const NODE = [
+  { name: "Node.js", slug: "node", version: "" },
+  { name: "Node.js", slug: "node~10_lts", version: "10 LTS" },
+  { name: "Node.js", slug: "node~8_lts", version: "8 LTS" },
+];
+const BASH = [{ name: "Bash", slug: "bash" }];
+
+const newDoc = (attributes) => new app.models.Doc(attributes);
+const findLatest = (slug, attributes) => {
+  const docs = attributes.map(newDoc);
+  return docs.find((doc) => doc.slug === slug).findLatestVersion(docs).slug;
+};
+
+test("the latest version of a documentation compares versions numerically", () => {
+  assert.equal(findLatest("cmake~3.9", CMAKE), "cmake~3.12");
+  assert.equal(findLatest("cmake~3.12", CMAKE), "cmake~3.12");
+  assert.equal(
+    findLatest("bazel~9", [
+      { name: "Bazel", slug: "bazel~10", version: "10" },
+      { name: "Bazel", slug: "bazel~9", version: "9" },
+    ]),
+    "bazel~10",
+  );
+});
+
+test("a documentation without a version is the latest version", () => {
+  const docs = [
+    { name: "Angular", slug: "angular", version: "" },
+    { name: "Angular", slug: "angular~5", version: "5" },
+  ];
+  assert.equal(findLatest("angular~5", docs), "angular");
+  assert.equal(findLatest("angular", docs), "angular");
+});
+
+test("documentations that aren't versioned have no latest version", () => {
+  assert.equal(findLatest("bash", BASH), "bash");
+});
+
+test("variants of a documentation aren't versions", () => {
+  // Node.js 10 LTS isn't superseded by the unversioned (latest) Node.js doc,
+  // and neither is a Haxe target by the base Haxe doc.
+  assert.equal(findLatest("node~10_lts", NODE), "node~10_lts");
+  assert.equal(
+    findLatest("haxe~python", [
+      { name: "Haxe", slug: "haxe", version: "" },
+      { name: "Haxe", slug: "haxe~python", version: "Python" },
+    ]),
+    "haxe~python",
+  );
+});
+
+const migrate = (enabled, allDocs, autoLatestVersion = true) => {
+  app.settings = {
+    get: (key) => (key === "autoLatestVersion" ? autoLatestVersion : undefined),
+  };
+  app.docs = new app.collections.Docs();
+  app.disabledDocs = new app.collections.Docs();
+  for (const attributes of allDocs) {
+    (enabled.includes(attributes.slug) ? app.docs : app.disabledDocs).add(
+      attributes,
+    );
+  }
+  app.saveDocs = () => {
+    app.saved = true;
+  };
+  app.saved = false;
+  app.migrateToLatestVersions();
+  // Spread the array so that it's created in this realm, not the VM's.
+  return [...app.docs.all().map((doc) => doc.slug)];
+};
+
+test("enabled docs are migrated to their latest version at boot", () => {
+  assert.deepEqual(migrate(["cmake~3.9", "bash"], [...CMAKE, ...BASH]), [
+    "bash",
+    "cmake~3.12",
+  ]);
+  assert.equal(app.saved, true);
+  assert.equal(app.disabledDocs.findBy("slug", "cmake~3.9").slug, "cmake~3.9");
+});
+
+test("outdated docs are disabled when their latest version is already enabled", () => {
+  assert.deepEqual(migrate(["cmake~3.9", "cmake~3.12"], CMAKE), ["cmake~3.12"]);
+});
+
+test("docs are left alone without the preference or a newer version", () => {
+  assert.deepEqual(migrate(["cmake~3.9"], CMAKE, false), ["cmake~3.9"]);
+  assert.equal(app.saved, false);
+
+  assert.deepEqual(
+    migrate(["cmake~3.12", "node~10_lts"], [...CMAKE, ...NODE]),
+    ["cmake~3.12", "node~10_lts"],
+  );
+  assert.equal(app.saved, false);
+});

From 0395aac52186097eb5d01095beba580db149f9ba Mon Sep 17 00:00:00 2001
From: Simon Legner <Simon.Legner@gmail.com>
Date: Mon, 14 Sep 2026 09:34:58 +0200
Subject: [PATCH 2/4] Replace a doc only once its latest version has loaded

saveDocs bumps the database schema, which drops the object store of the doc
that is disabled. Swapping before the index of the latest version is known to
load left a boot that fails, e.g. an offline one, with neither the version
that was installed nor the one that replaced it.

The index is now loaded first and the swap is made in its success callback,
so a doc that can't be fetched stays enabled and nothing is persisted.
---
 assets/javascripts/app/app.js   | 65 ++++++++++++++++++++++-----------
 test/assets/doc_version_test.js | 26 ++++++++++++-
 2 files changed, 69 insertions(+), 22 deletions(-)

diff --git a/assets/javascripts/app/app.js b/assets/javascripts/app/app.js
index fc063b821d..82b36688a3 100644
--- a/assets/javascripts/app/app.js
+++ b/assets/javascripts/app/app.js
@@ -123,10 +123,11 @@ class App extends Events {
       (docs.includes(doc.slug) ? this.docs : this.disabledDocs).add(doc);
     }
     this.migrateDocs();
-    this.migrateToLatestVersions();
-    this.docs.load(this.start.bind(this), this.onBootError.bind(this), {
-      readCache: true,
-      writeCache: true,
+    this.migrateToLatestVersions(() => {
+      this.docs.load(this.start.bind(this), this.onBootError.bind(this), {
+        readCache: true,
+        writeCache: true,
+      });
     });
     delete this.DOCS;
   }
@@ -192,33 +193,55 @@ class App extends Events {
   }
 
   // With the "latest version" preference enabled, replace the enabled docs for
-  // which a newer version is available with that version.
-  migrateToLatestVersions() {
+  // which a newer version is available with that version. A doc is only
+  // replaced once the index of its latest version has loaded, because saving
+  // drops the offline data of the doc that is disabled.
+  migrateToLatestVersions(callback) {
     if (!this.settings.get("autoLatestVersion")) {
+      callback();
       return;
     }
 
-    let needsSaving;
     const allDocs = this.docs.all().concat(this.disabledDocs.all());
+    const migrations = [];
 
-    for (var doc of this.docs.all().slice()) {
+    for (var doc of this.docs.all()) {
       var latest = doc.findLatestVersion(allDocs);
-      if (latest === doc) {
-        continue;
+      if (latest !== doc) {
+        migrations.push([doc, latest]);
       }
-      this.docs.remove(doc);
-      this.disabledDocs.add(doc);
-      if (!this.docs.contains(latest)) {
-        this.disabledDocs.remove(latest);
-        this.docs.add(latest);
-      }
-      needsSaving = true;
     }
 
-    if (needsSaving) {
-      this.docs.sort();
-      this.saveDocs();
-    }
+    let i = 0;
+    let needsSaving;
+
+    var next = () => {
+      if (i === migrations.length) {
+        if (needsSaving) {
+          this.docs.sort();
+          this.saveDocs();
+        }
+        callback();
+        return;
+      }
+
+      const [outdated, latest] = migrations[i++];
+
+      const onSuccess = () => {
+        this.docs.remove(outdated);
+        this.disabledDocs.add(outdated);
+        if (!this.docs.contains(latest)) {
+          this.disabledDocs.remove(latest);
+          this.docs.add(latest);
+        }
+        needsSaving = true;
+        next();
+      };
+
+      latest.load(onSuccess, next, { readCache: true, writeCache: true });
+    };
+
+    next();
   }
 
   enableDoc(doc, _onSuccess, onError) {
diff --git a/test/assets/doc_version_test.js b/test/assets/doc_version_test.js
index 527c52fbdf..e7e1e37e15 100644
--- a/test/assets/doc_version_test.js
+++ b/test/assets/doc_version_test.js
@@ -97,6 +97,15 @@ test("variants of a documentation aren't versions", () => {
   );
 });
 
+// The index of the latest version has to load for a doc to be replaced.
+app.models.Doc.prototype.load = function (onSuccess, onError) {
+  if (app.loadFails) {
+    onError();
+  } else {
+    onSuccess();
+  }
+};
+
 const migrate = (enabled, allDocs, autoLatestVersion = true) => {
   app.settings = {
     get: (key) => (key === "autoLatestVersion" ? autoLatestVersion : undefined),
@@ -112,7 +121,10 @@ const migrate = (enabled, allDocs, autoLatestVersion = true) => {
     app.saved = true;
   };
   app.saved = false;
-  app.migrateToLatestVersions();
+  app.booted = false;
+  app.migrateToLatestVersions(() => {
+    app.booted = true;
+  });
   // Spread the array so that it's created in this realm, not the VM's.
   return [...app.docs.all().map((doc) => doc.slug)];
 };
@@ -123,6 +135,7 @@ test("enabled docs are migrated to their latest version at boot", () => {
     "cmake~3.12",
   ]);
   assert.equal(app.saved, true);
+  assert.equal(app.booted, true);
   assert.equal(app.disabledDocs.findBy("slug", "cmake~3.9").slug, "cmake~3.9");
 });
 
@@ -130,6 +143,17 @@ test("outdated docs are disabled when their latest version is already enabled",
   assert.deepEqual(migrate(["cmake~3.9", "cmake~3.12"], CMAKE), ["cmake~3.12"]);
 });
 
+test("a doc whose latest version fails to load isn't replaced", () => {
+  app.loadFails = true;
+  try {
+    assert.deepEqual(migrate(["cmake~3.9"], CMAKE), ["cmake~3.9"]);
+    assert.equal(app.saved, false);
+    assert.equal(app.booted, true);
+  } finally {
+    app.loadFails = false;
+  }
+});
+
 test("docs are left alone without the preference or a newer version", () => {
   assert.deepEqual(migrate(["cmake~3.9"], CMAKE, false), ["cmake~3.9"]);
   assert.equal(app.saved, false);

From 0cfe22e3cae29bd34576374e61eabf2b0d621d2f Mon Sep 17 00:00:00 2001
From: Simon Legner <Simon.Legner@gmail.com>
Date: Mon, 14 Sep 2026 09:37:31 +0200
Subject: [PATCH 3/4] Use async/await for the version migration

Awaiting the index of the latest version reads better than chaining the
migrations through callbacks, and bootAll can wait for them before loading
the enabled docs.
---
 assets/javascripts/app/app.js   | 82 +++++++++++++++------------------
 test/assets/doc_version_test.js | 29 ++++++------
 2 files changed, 50 insertions(+), 61 deletions(-)

diff --git a/assets/javascripts/app/app.js b/assets/javascripts/app/app.js
index 82b36688a3..2fea07e207 100644
--- a/assets/javascripts/app/app.js
+++ b/assets/javascripts/app/app.js
@@ -117,19 +117,18 @@ class App extends Events {
     delete this.DOC;
   }
 
-  bootAll() {
+  async bootAll() {
     const docs = this.settings.getDocs();
     for (var doc of this.DOCS) {
       (docs.includes(doc.slug) ? this.docs : this.disabledDocs).add(doc);
     }
+    delete this.DOCS;
     this.migrateDocs();
-    this.migrateToLatestVersions(() => {
-      this.docs.load(this.start.bind(this), this.onBootError.bind(this), {
-        readCache: true,
-        writeCache: true,
-      });
+    await this.migrateToLatestVersions();
+    this.docs.load(this.start.bind(this), this.onBootError.bind(this), {
+      readCache: true,
+      writeCache: true,
     });
-    delete this.DOCS;
   }
 
   start() {
@@ -193,55 +192,48 @@ class App extends Events {
   }
 
   // With the "latest version" preference enabled, replace the enabled docs for
-  // which a newer version is available with that version. A doc is only
-  // replaced once the index of its latest version has loaded, because saving
-  // drops the offline data of the doc that is disabled.
-  migrateToLatestVersions(callback) {
+  // which a newer version is available with that version.
+  async migrateToLatestVersions() {
     if (!this.settings.get("autoLatestVersion")) {
-      callback();
       return;
     }
 
     const allDocs = this.docs.all().concat(this.disabledDocs.all());
-    const migrations = [];
-
-    for (var doc of this.docs.all()) {
-      var latest = doc.findLatestVersion(allDocs);
-      if (latest !== doc) {
-        migrations.push([doc, latest]);
-      }
-    }
-
-    let i = 0;
     let needsSaving;
 
-    var next = () => {
-      if (i === migrations.length) {
-        if (needsSaving) {
-          this.docs.sort();
-          this.saveDocs();
-        }
-        callback();
-        return;
+    for (var outdated of this.docs.all().slice()) {
+      var latest = outdated.findLatestVersion(allDocs);
+      if (latest === outdated) {
+        continue;
       }
 
-      const [outdated, latest] = migrations[i++];
-
-      const onSuccess = () => {
-        this.docs.remove(outdated);
-        this.disabledDocs.add(outdated);
-        if (!this.docs.contains(latest)) {
-          this.disabledDocs.remove(latest);
-          this.docs.add(latest);
-        }
-        needsSaving = true;
-        next();
-      };
+      // Saving drops the offline data of the doc that is disabled, so the
+      // index of its latest version has to load before the swap is made.
+      const loaded = await new Promise((resolve) =>
+        latest.load(
+          () => resolve(true),
+          () => resolve(false),
+          { readCache: true, writeCache: true },
+        ),
+      );
+
+      if (!loaded) {
+        continue;
+      }
 
-      latest.load(onSuccess, next, { readCache: true, writeCache: true });
-    };
+      this.docs.remove(outdated);
+      this.disabledDocs.add(outdated);
+      if (!this.docs.contains(latest)) {
+        this.disabledDocs.remove(latest);
+        this.docs.add(latest);
+      }
+      needsSaving = true;
+    }
 
-    next();
+    if (needsSaving) {
+      this.docs.sort();
+      this.saveDocs();
+    }
   }
 
   enableDoc(doc, _onSuccess, onError) {
diff --git a/test/assets/doc_version_test.js b/test/assets/doc_version_test.js
index e7e1e37e15..db0f508c93 100644
--- a/test/assets/doc_version_test.js
+++ b/test/assets/doc_version_test.js
@@ -106,7 +106,7 @@ app.models.Doc.prototype.load = function (onSuccess, onError) {
   }
 };
 
-const migrate = (enabled, allDocs, autoLatestVersion = true) => {
+const migrate = async (enabled, allDocs, autoLatestVersion = true) => {
   app.settings = {
     get: (key) => (key === "autoLatestVersion" ? autoLatestVersion : undefined),
   };
@@ -121,45 +121,42 @@ const migrate = (enabled, allDocs, autoLatestVersion = true) => {
     app.saved = true;
   };
   app.saved = false;
-  app.booted = false;
-  app.migrateToLatestVersions(() => {
-    app.booted = true;
-  });
+  await app.migrateToLatestVersions();
   // Spread the array so that it's created in this realm, not the VM's.
   return [...app.docs.all().map((doc) => doc.slug)];
 };
 
-test("enabled docs are migrated to their latest version at boot", () => {
-  assert.deepEqual(migrate(["cmake~3.9", "bash"], [...CMAKE, ...BASH]), [
+test("enabled docs are migrated to their latest version at boot", async () => {
+  assert.deepEqual(await migrate(["cmake~3.9", "bash"], [...CMAKE, ...BASH]), [
     "bash",
     "cmake~3.12",
   ]);
   assert.equal(app.saved, true);
-  assert.equal(app.booted, true);
   assert.equal(app.disabledDocs.findBy("slug", "cmake~3.9").slug, "cmake~3.9");
 });
 
-test("outdated docs are disabled when their latest version is already enabled", () => {
-  assert.deepEqual(migrate(["cmake~3.9", "cmake~3.12"], CMAKE), ["cmake~3.12"]);
+test("outdated docs are disabled when their latest version is already enabled", async () => {
+  assert.deepEqual(await migrate(["cmake~3.9", "cmake~3.12"], CMAKE), [
+    "cmake~3.12",
+  ]);
 });
 
-test("a doc whose latest version fails to load isn't replaced", () => {
+test("a doc whose latest version fails to load isn't replaced", async () => {
   app.loadFails = true;
   try {
-    assert.deepEqual(migrate(["cmake~3.9"], CMAKE), ["cmake~3.9"]);
+    assert.deepEqual(await migrate(["cmake~3.9"], CMAKE), ["cmake~3.9"]);
     assert.equal(app.saved, false);
-    assert.equal(app.booted, true);
   } finally {
     app.loadFails = false;
   }
 });
 
-test("docs are left alone without the preference or a newer version", () => {
-  assert.deepEqual(migrate(["cmake~3.9"], CMAKE, false), ["cmake~3.9"]);
+test("docs are left alone without the preference or a newer version", async () => {
+  assert.deepEqual(await migrate(["cmake~3.9"], CMAKE, false), ["cmake~3.9"]);
   assert.equal(app.saved, false);
 
   assert.deepEqual(
-    migrate(["cmake~3.12", "node~10_lts"], [...CMAKE, ...NODE]),
+    await migrate(["cmake~3.12", "node~10_lts"], [...CMAKE, ...NODE]),
     ["cmake~3.12", "node~10_lts"],
   );
   assert.equal(app.saved, false);

From 3978fc96f1867a4af2c23b6e5a554534cfde6973 Mon Sep 17 00:00:00 2001
From: Simon Legner <Simon.Legner@gmail.com>
Date: Mon, 14 Sep 2026 09:43:46 +0200
Subject: [PATCH 4/4] Load the latest versions with a bounded concurrency

Awaiting one index after the other delayed the boot of everyone whose docs
are several releases behind. The indexes are now loaded through as many
parallel requests as Docs#load makes, and a version superseding more than one
enabled doc is only loaded once.
---
 assets/javascripts/app/app.js   | 69 +++++++++++++++++++++++++--------
 test/assets/doc_version_test.js |  9 +++++
 2 files changed, 61 insertions(+), 17 deletions(-)

diff --git a/assets/javascripts/app/app.js b/assets/javascripts/app/app.js
index 2fea07e207..f05b963dd5 100644
--- a/assets/javascripts/app/app.js
+++ b/assets/javascripts/app/app.js
@@ -199,30 +199,32 @@ class App extends Events {
     }
 
     const allDocs = this.docs.all().concat(this.disabledDocs.all());
-    let needsSaving;
+    // The same version can supersede several enabled docs, so it's only loaded
+    // once, e.g. when both CMake 3.9 and CMake 3.10 are enabled.
+    const migrations = new Map();
 
-    for (var outdated of this.docs.all().slice()) {
-      var latest = outdated.findLatestVersion(allDocs);
+    for (const outdated of this.docs.all()) {
+      const latest = outdated.findLatestVersion(allDocs);
       if (latest === outdated) {
         continue;
       }
+      if (!migrations.has(latest)) {
+        migrations.set(latest, []);
+      }
+      migrations.get(latest).push(outdated);
+    }
+
+    const loaded = await this.loadLatestVersions([...migrations.keys()]);
+    let needsSaving;
 
-      // Saving drops the offline data of the doc that is disabled, so the
-      // index of its latest version has to load before the swap is made.
-      const loaded = await new Promise((resolve) =>
-        latest.load(
-          () => resolve(true),
-          () => resolve(false),
-          { readCache: true, writeCache: true },
-        ),
-      );
-
-      if (!loaded) {
+    for (const [latest, outdatedDocs] of migrations) {
+      if (!loaded.has(latest)) {
         continue;
       }
-
-      this.docs.remove(outdated);
-      this.disabledDocs.add(outdated);
+      for (const outdated of outdatedDocs) {
+        this.docs.remove(outdated);
+        this.disabledDocs.add(outdated);
+      }
       if (!this.docs.contains(latest)) {
         this.disabledDocs.remove(latest);
         this.docs.add(latest);
@@ -236,6 +238,39 @@ class App extends Events {
     }
   }
 
+  // Saving drops the offline data of the docs that are disabled, so the index
+  // of their latest version has to load before they are replaced. Loads no
+  // more docs at once than Docs#load does.
+  async loadLatestVersions(docs) {
+    const loaded = new Set();
+    let i = 0;
+
+    const next = async () => {
+      while (i < docs.length) {
+        const doc = docs[i++];
+        const success = await new Promise((resolve) =>
+          doc.load(
+            () => resolve(true),
+            () => resolve(false),
+            { readCache: true, writeCache: true },
+          ),
+        );
+        if (success) {
+          loaded.add(doc);
+        }
+      }
+    };
+
+    await Promise.all(
+      Array.from(
+        { length: Math.min(docs.length, app.collections.Docs.CONCURRENCY) },
+        next,
+      ),
+    );
+
+    return loaded;
+  }
+
   enableDoc(doc, _onSuccess, onError) {
     if (this.docs.contains(doc)) {
       return;
diff --git a/test/assets/doc_version_test.js b/test/assets/doc_version_test.js
index db0f508c93..448d815f16 100644
--- a/test/assets/doc_version_test.js
+++ b/test/assets/doc_version_test.js
@@ -99,6 +99,7 @@ test("variants of a documentation aren't versions", () => {
 
 // The index of the latest version has to load for a doc to be replaced.
 app.models.Doc.prototype.load = function (onSuccess, onError) {
+  app.loads.push(this.slug);
   if (app.loadFails) {
     onError();
   } else {
@@ -121,6 +122,7 @@ const migrate = async (enabled, allDocs, autoLatestVersion = true) => {
     app.saved = true;
   };
   app.saved = false;
+  app.loads = [];
   await app.migrateToLatestVersions();
   // Spread the array so that it's created in this realm, not the VM's.
   return [...app.docs.all().map((doc) => doc.slug)];
@@ -141,6 +143,13 @@ test("outdated docs are disabled when their latest version is already enabled",
   ]);
 });
 
+test("the version superseding several docs is only loaded once", async () => {
+  assert.deepEqual(await migrate(["cmake~3.9", "cmake~3.10"], CMAKE), [
+    "cmake~3.12",
+  ]);
+  assert.deepEqual([...app.loads], ["cmake~3.12"]);
+});
+
 test("a doc whose latest version fails to load isn't replaced", async () => {
   app.loadFails = true;
   try {