Offer several bilby versions, with a picker on the page

.github/workflows/pages.yml

@@ -4,7 +4,7 @@
 #
 # Nothing the site serves from examples/ or wheels/ is stored in the
 # repository: the examples and the bilby wheel come from the commit pinned in
-# bilby-commit.txt, igwn-segments is rebuilt from its sdist, the LALSuite
+# bilby-versions.json, igwn-segments is rebuilt from its sdist, the LALSuite
 # wheel is downloaded from the GitLab job pinned in lalsuite-wheel.json, and
 # the PyPI wheels pinned in packages.lock.json are served by the site too.
 name: Deploy to GitHub Pages
@@ -48,7 +48,7 @@ jobs:
           path: |
             wheels
             .cache
-          key: site-${{ hashFiles('bilby-commit.txt', 'lalsuite-wheel.json', 'packages.lock.json', 'scripts/fetch-bilby.sh', 'scripts/build-igwn-segments.sh') }}
+          key: site-${{ hashFiles('bilby-versions.json', 'lalsuite-wheel.json', 'packages.lock.json', 'scripts/fetch-bilby.sh', 'scripts/build-igwn-segments.sh') }}
 
       - name: Build the code editor (CodeMirror)
         run: |

.github/workflows/tests.yml

@@ -1,5 +1,6 @@
-# Test the examples and the page. Independent of deployment (pages.yml):
-# failures here are reported but do not stop the site from deploying.
+# Test the examples and the page, in one job per bilby version in
+# bilby-versions.json. Independent of deployment (pages.yml): failures here
+# are reported but do not stop the site from deploying.
 name: Tests
 
 on:
@@ -16,8 +17,23 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  versions:
+    runs-on: ubuntu-latest
+    outputs:
+      names: ${{ steps.names.outputs.names }}
+    steps:
+      - uses: actions/checkout@v4
+      - id: names
+        run: echo "names=$(jq -c '[.versions[].name]' bilby-versions.json)" >> "$GITHUB_OUTPUT"
+
   test:
+    needs: versions
+    name: test (bilby ${{ matrix.bilby }})
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        bilby: ${{ fromJSON(needs.versions.outputs.names) }}
     steps:
       - uses: actions/checkout@v4
 
@@ -35,7 +51,7 @@ jobs:
           path: |
             wheels
             .cache
-          key: site-${{ hashFiles('bilby-commit.txt', 'lalsuite-wheel.json', 'packages.lock.json', 'scripts/fetch-bilby.sh', 'scripts/build-igwn-segments.sh') }}
+          key: site-${{ hashFiles('bilby-versions.json', 'lalsuite-wheel.json', 'packages.lock.json', 'scripts/fetch-bilby.sh', 'scripts/build-igwn-segments.sh') }}
 
       - name: Install Node tools and build the code editor
         run: |
@@ -63,9 +79,10 @@ jobs:
         run: npx playwright install --with-deps chromium
 
       - name: Run every supported example in Node (bilby test mode)
-        run: node scripts/test-all.mjs
+        run: node scripts/test-all.mjs --bilby "${{ matrix.bilby }}"
 
       - name: Smoke-test the assembled site in Chromium
         run: npx playwright test
         env:
           SITE_DIR: _site
+          BILBY_VERSION: ${{ matrix.bilby }}

LOCAL-ONLY.md

@@ -9,7 +9,7 @@ scripts in `scripts/` (run together by `scripts/dev.sh` locally and by
 
 | What | Source |
 |---|---|
-| `examples/`, `wheels/bilby-*.whl` | bilby commit pinned in `bilby-commit.txt` (`scripts/fetch-bilby.sh`) |
+| `examples/`, `wheels/bilby-*.whl` | bilby commits pinned in `bilby-versions.json` (`scripts/fetch-bilby.sh`) |
 | `wheels/igwn_segments-*.whl` | igwn-segments sdist from PyPI (`scripts/build-igwn-segments.sh`) |
 | `wheels/lalsuite-*.whl` | GitLab job artifact pinned with sha256 in `lalsuite-wheel.json` (`scripts/fetch-lalsuite.sh`) |
 

PLAN.md

@@ -60,8 +60,9 @@ Pyodide. Background on the LALSuite Pyodide build is in `NOTES.md`.
 - **32-bit WebAssembly**: floats are 64-bit, but sizes and numpy's default
   integer are 32-bit (details in `NOTES.md`). scipy's spectral helper
   `_fft_helper` is replaced so PSDs do not hit numpy's 2 GB view limit.
-- **bilby and examples** come from one pinned commit of bilby-dev/bilby
-  `main` (`bilby-commit.txt`; `scripts/fetch-bilby.sh --update` moves it).
+- **bilby and examples** come from pinned commits of bilby-dev/bilby, one
+  per version the page offers (`bilby-versions.json`: releases and `main`;
+  `scripts/fetch-bilby.sh --update` moves `main`).
   `scripts/adapt_examples.py` edits them for Pyodide (pymultinest → nestle,
   cpnest → dynesty, `npool=` lines removed) and flags unsupported ones; the
   page shows both. Neither examples nor wheels are stored in git.

README.md

@@ -6,16 +6,26 @@ for background and `LOCAL-ONLY.md` for what is still tied to this machine.
 
 ## Where bilby comes from
 
-`bilby-commit.txt` pins one commit of
-[bilby-dev/bilby](https://github.com/bilby-dev/bilby). `scripts/fetch-bilby.sh`
-takes both the examples (`examples/`, without notebooks) and a bilby wheel
-(`wheels/`) from that commit, so the examples always match the bilby that runs
-them. Neither is stored in this repository. To move to the current `main`:
+The page offers several bilby versions, listed in `bilby-versions.json`
+(currently 2.8.2, the default, 2.7.1, 2.6.0 and `main`), each pinned to a
+commit of [bilby-dev/bilby](https://github.com/bilby-dev/bilby). The picker
+in the header switches between them (it restarts Python and keeps the open
+example, with any edits), and `?bilby=<name>` in the URL picks one.
+`scripts/fetch-bilby.sh` takes both the examples (`examples/<name>/`, without
+notebooks) and a bilby wheel (`wheels/`) from each version's commit, so the
+examples always match the bilby that runs them. Neither is stored in this
+repository. To move `main` to the current head:
 
 ```bash
 scripts/fetch-bilby.sh --update
 ```
 
+To add a version, add it to `bilby-versions.json` (with `pins` if it needs
+older dependencies than `py/bootstrap.py` asks for, as 2.6.0 does for
+dynesty), then run `scripts/fetch-bilby.sh` and `node scripts/lock-packages.mjs`.
+Everything else (LALSuite, the other wheels, the page) is shared by all
+versions.
+
 ## Other wheels
 
 `wheels/` is generated, never committed:
@@ -49,12 +59,14 @@ https://colmtalbot.github.io/bilby-browser/. It runs the scripts above to genera
 npm install
 npx playwright install chromium   # once
 scripts/dev.sh                    # once, to generate examples/ and wheels/
-npm test                          # every supported example in Node (test mode)
+npm test                          # every supported example in Node (test mode), every bilby version
+npm test -- --bilby 2.6.0         # one bilby version
 npm run test:browser              # Playwright smoke test of the page
 python -m unittest tests/test_gwosc_range.py   # GWOSC range reads (needs gwpy==4.0.2)
 ```
 
-Expected failures are listed with reasons in `tests/known-failures.json`.
+Expected failures are listed with reasons in `tests/known-failures.json`,
+for every version or for one. CI tests each version in its own job.
 CI runs both before every deploy.
 
 ## Licences

app.js

@@ -15,7 +15,9 @@ const editor = BilbyEditor.createEditor($("code"), {
   placeholderText: "# A blank editor: bilby, its samplers and LALSuite are available.\n# Ctrl/⌘+Enter to run.",
 });
 let worker = null;
-let current = null; // {path, files, original}
+let current = null; // {path, version, files, original, header}
+let versions = null; // examples/versions.json
+let bilby = null; // the bilby version in use: an entry of versions.versions
 let running = false;
 
 // localStorage, which can be unavailable (private windows, blocked storage)
@@ -526,7 +528,9 @@ for (const tab of TABS) {
 // ---- worker ---------------------------------------------------------------
 
 function startWorker() {
-  worker = new Worker(versioned("worker.js"));
+  const url = new URL(versioned("worker.js"), location.href);
+  url.searchParams.set("bilby", bilby.name);
+  worker = new Worker(url.href);
   worker.ready = false;
   setRunning(false);
   setStatus("Starting Python…");
@@ -619,17 +623,22 @@ function run() {
   announce(`Running ${current.path.split("/").pop()}` + (testMode ? " in test mode" : ""));
   editor.markErrorLine(null);
   worker.postMessage({
-    type: "run", path: current.path, code: editor.getValue(), files: current.files, testMode,
+    type: "run", path: current.path, code: editor.getValue(), files: current.files,
+    filesFrom: current.version, testMode,
     logLevel: $("log-level").value,
     uploads: [...uploads].map(([name, { bytes }]) => ({ name, bytes })),
   });
 }
 
 function stop() {
   if (!running) return;
+  restartWorker("stopped; restarting Python", "error");
+}
+
+function restartWorker(message, cls) {
   worker.terminate();
-  append("stopped; restarting Python", "error");
-  announce("Stopped; restarting Python");
+  append(message, cls);
+  announce(message[0].toUpperCase() + message.slice(1));
   block = output;
   running = false;
   workerHasFiles = false;
@@ -710,36 +719,43 @@ $("search").addEventListener("keydown", (e) => {
   }
 });
 
-async function select(path) {
-  if (path === "scratch") return openScratch();
+// Open an example of the bilby version in use. With keepCode, the editor
+// keeps what it has (edits made to the same example in another version).
+// Returns false if this version has no such example.
+async function select(path, { keepCode = false } = {}) {
+  if (path === "scratch") {
+    openScratch();
+    return true;
+  }
   const link = document.querySelector(`#tree a[data-path="${CSS.escape(path)}"]`);
-  if (!link) return;
+  if (!link) return false;
   for (const a of document.querySelectorAll("#tree a.active")) a.classList.remove("active");
   link.classList.add("active");
   // open the folders containing this example
   for (let el = link.parentElement; el && el.id !== "tree"; el = el.parentElement) {
     if (el.tagName === "DETAILS") el.open = true;
   }
-  const response = await fetch(versioned("examples/" + path));
+  const response = await fetch(versioned(`examples/${bilby.name}/${path}`));
   // the shebang and docstring are shown as formatted text above the editor
   // instead of in it; Download puts them back
   const lines = (await response.text()).split("\n");
   const headerLines = Number(link.dataset.headerLines);
   const code = lines.slice(headerLines).join("\n");
   current = {
-    path, files: JSON.parse(link.dataset.files), original: code,
+    path, version: bilby.name, files: JSON.parse(link.dataset.files), original: code,
     header: headerLines ? lines.slice(0, headerLines).join("\n") + "\n" : "",
   };
-  editor.load(code);
+  if (!keepCode) editor.load(code);
   $("title").textContent = path;
   showDoc(JSON.parse(link.dataset.doc));
   showNotes(JSON.parse(link.dataset.info));
+  return true;
 }
 
 // A blank editor, not tied to an example; its text is kept in this browser.
 function openScratch() {
   for (const a of document.querySelectorAll("#tree a.active")) a.classList.remove("active");
-  current = { path: SCRATCH, files: [], original: "", header: "" };
+  current = { path: SCRATCH, version: bilby.name, files: [], original: "", header: "" };
   editor.load(stored("bilby-scratch") || "");
   $("title").textContent = SCRATCH;
   showDoc(["<p>A blank editor. Its contents are kept in this browser; Reset clears it.</p>"]);
@@ -794,18 +810,65 @@ function showNotes({ changes, support }) {
   }
 }
 
-async function main() {
-  const manifest = await (await fetch(versioned("examples/manifest.json"))).json();
+// ---- bilby versions ------------------------------------------------------
+// The page offers each version in examples/versions.json; ?bilby=<name> in
+// its URL picks one (the default otherwise). Switching restarts Python with
+// that version and keeps the example open, with any edits.
+
+const DEFAULT_EXAMPLE = "core_examples/linear_regression.py";
+
+// Show the examples of this version (bilby and its tree; not the worker).
+async function showVersion(name) {
+  bilby = versions.versions.find((v) => v.name === name);
+  $("bilby-version").value = name;
+  $("bilby-version").title = `bilby ${bilby.version}: the version the examples come from and run with`;
+  const manifest = await (await fetch(versioned(`examples/${name}/manifest.json`))).json();
   const tree = document.createElement("div");
+  tree.id = "examples";
   buildTree(manifest, tree);
+  $("examples")?.remove();
   $("tree").insertBefore(tree, $("tree").querySelector(".links")); // links stay last (phones)
-  if (manifest.commit) {
-    const link = $("source");
-    link.href = `https://github.com/bilby-dev/bilby/tree/${manifest.commit}/examples`;
-    link.textContent = `examples from bilby@${manifest.commit.slice(0, 8)}`;
+  if ($("search").value) filterTree($("search").value);
+  const link = $("source");
+  link.href = `https://github.com/bilby-dev/bilby/tree/${bilby.tag || bilby.commit}/examples`;
+  link.textContent = bilby.tag ? `examples from bilby ${bilby.tag}` : `examples from bilby@${bilby.commit.slice(0, 8)}`;
+}
+
+async function switchVersion(name) {
+  const url = new URL(location.href);
+  if (name === versions.default) url.searchParams.delete("bilby");
+  else url.searchParams.set("bilby", name);
+  history.replaceState(null, "", url);
+  const before = current;
+  const edited = editor.getValue() !== before.original;
+  await showVersion(name);
+  const label = bilby.version === name ? name : `${name} (${bilby.version})`;
+  restartWorker(`switched to bilby ${label}; restarting Python`, "info");
+  if (before.path === SCRATCH) return;
+  if (await select(before.path, { keepCode: edited })) {
+    if (edited) append(`kept your edits to ${before.path}; Reset gives bilby ${name}'s version`, "info");
+  } else {
+    // not an example in this version: keep it (and its data files) as it was
+    current = before;
+    append(`${before.path} is not one of bilby ${name}'s examples; it stays open, from bilby ${before.version}`, "info");
   }
+}
+
+async function main() {
+  versions = await (await fetch(versioned("examples/versions.json"))).json();
+  const picker = $("bilby-version");
+  for (const v of versions.versions) picker.add(new Option(v.name, v.name));
+  const wanted = new URLSearchParams(location.search).get("bilby");
+  await showVersion(versions.versions.some((v) => v.name === wanted) ? wanted : versions.default);
+  startWorker();
+  picker.addEventListener("change", () => switchVersion(picker.value));
   window.addEventListener("hashchange", () => select(decodeURIComponent(location.hash.slice(1))));
-  await select(decodeURIComponent(location.hash.slice(1)) || "core_examples/linear_regression.py");
+  const path = decodeURIComponent(location.hash.slice(1));
+  if (!(await select(path || DEFAULT_EXAMPLE)) && path) {
+    append(`${path} is not one of bilby ${bilby.name}'s examples`, "info");
+    history.replaceState(null, "", "#" + DEFAULT_EXAMPLE);
+    await select(DEFAULT_EXAMPLE);
+  }
 }
 
 // bilby test mode: on by default when served locally (development), off on
@@ -1020,5 +1083,4 @@ $("theme").addEventListener("click", () => {
 });
 $("reset").addEventListener("click", () => { if (current) editor.reset(current.original); });
 
-startWorker();
 main();

bilby-versions.json

@@ -0,0 +1,10 @@
+{
+ "_comment": "The bilby versions the site offers, in the order of the page's picker. Each is pinned to a commit of github.com/bilby-dev/bilby; releases also name their tag. pins replace the matching specs of the bilby group in py/bootstrap.py when scripts/lock-packages.mjs resolves that version. scripts/fetch-bilby.sh --update moves main to the current head.",
+ "default": "2.8.2",
+ "versions": [
+  {"name": "2.8.2", "tag": "v2.8.2", "commit": "9d0e91e31abfe0f716152bb06d2b496783520add"},
+  {"name": "2.7.1", "tag": "v2.7.1", "commit": "710e1808741c55245d4fcc2b5603f7b2f15e5ae5"},
+  {"name": "2.6.0", "tag": "v2.6.0", "commit": "80963a7b46473f9a1ccef839444a3d686da2ad2d", "pins": ["dynesty==2.1.5"]},
+  {"name": "main", "commit": "f2d0363470410172aae8cbbe6452fcd3a1d1f41c"}
+ ]
+}

index.html

@@ -318,6 +318,7 @@
     #status { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
     .toggle, .log-level { flex: none; }
     .log-level > span { display: none; }
+    nav .links .bilby-version > span { display: inline; }
     .log-level select { font-size: 12px; padding: 2px 0; }
     main, body.tree-hidden main, body.editor-hidden main, body.output-hidden main { grid-template-columns: minmax(0, 1fr); padding: 10px 12px; gap: 12px; }
     nav, body.tree-hidden nav { display: flex; position: fixed; z-index: 30; top: 0; bottom: 0; left: 0;
@@ -382,6 +383,10 @@ <h1><img src="assets/bilby-logo.jpg" alt="Bilby" title="Bilby" width="28" height
     </select>
   </label>
   <span class="links hint">
+    <label class="log-level bilby-version">
+      <span>bilby</span>
+      <select id="bilby-version" aria-label="bilby version"></select>
+    </label>
     <a id="source"></a>
     <a href="https://github.com/ColmTalbot/bilby-browser">Site source</a>
     <a href="licenses.html">Licences</a>