From 9726ec98553f3a6008a17ec3b546be7912a2acff Mon Sep 17 00:00:00 2001 From: lmoresi Date: Mon, 7 Sep 2026 09:00:45 -0700 Subject: [PATCH 1/2] An updated note says what changed, and where the old one is We had the machinery and not the statement. Figshare mints a version DOI per deposit and the concept DOI resolves to the newest, so previous versions have always been retrievable -- but nothing in a note told a reader it had moved, or what moved. The one thing every correction policy agrees on is that a published article is never changed silently. So an updated note carries a `## History` section: one entry per DEPOSITED version, newest first, with the version, the date, the version DOI, what changed and -- when it applies -- what did not. That last part is the useful half when an API moved and the physics did not: it is what saves a reader from re-reading the note to find out. Only deposited versions appear. A typo fix is a patch bump with no deposit and leaves no trace, or the section fills with corrections nobody needs and the ones that matter are lost among them. The live page carries the current history and each deposited PDF carries the history up to its own version. That is correct rather than a defect, and it is why nothing goes back to amend an older PDF: a deposited copy is a fixed document, and the version DOIs are what connect them. A test notices a note deposited past 1.0.0 with no History section, since this is exactly the kind of step that gets forgotten. It found one immediately -- the browser note, deposited at 1.1.0 in August and silent about it -- which now has its entries. Underworld development team with AI support from Claude Code --- CONTRIBUTING.md | 6 +++ PUBLISHING.md | 33 +++++++++++++++++ .../running-underworld-in-a-browser.md | 10 +++++ templates/article-template/ARTICLE.md | 13 +++++++ tests/test_migration.py | 37 +++++++++++++++++++ 5 files changed, 99 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3c0064..c1725bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -236,6 +236,12 @@ something works, not how hard it was to make work. the reason to write *that* note, not to reference it from this one. Say the general thing the reader can check, and leave the specific one to its own note. +- **An updated note carries a `## History` section**, and only versions that + were deposited appear in it: a version, a date, the version DOI, what changed + and — when it applies — what did not. A published note is never changed + silently. The live page shows the current history and each deposited PDF + shows the history up to its own version, so nothing goes back to amend an + older PDF. See PUBLISHING.md. - **Every figure and table ships the script that made it**, in the note's `examples/`. A number a reader cannot regenerate is an assertion. - **Alt text describes what the image shows, including the numbers.** It is read diff --git a/PUBLISHING.md b/PUBLISHING.md index aac326b..2d90c3b 100644 --- a/PUBLISHING.md +++ b/PUBLISHING.md @@ -58,6 +58,39 @@ updates to a published article affect only the private copy until an explicit publish. That matches the brief: cosmetic web corrections need no deposit, and a substantive change is a new version. +### The History section + +An updated note says so, in a `## History` section at the end. Never change a +published note silently: that is the one thing every correction policy agrees +on, because a reader who has the old text has no way to know it moved. + +Each entry is a version, a date, the version DOI, and a sentence on what +changed: + +```markdown +## History + +- **1.1.0** — 2026-09-08 · [10.6084/m9.figshare.33216996.v2](https://doi.org/10.6084/m9.figshare.33216996.v2) + Rewritten for the new time-stepping interface: `foo()` replaces `bar()`. + The method and the results are unchanged. +- **1.0.0** — 2026-08-11 · [10.6084/m9.figshare.33216996.v1](https://doi.org/10.6084/m9.figshare.33216996.v1) + First published. +``` + +**Say what did NOT change.** When an API moved and the physics did not, that +sentence is what saves a reader from re-reading the note to find out. + +**Only deposited versions get an entry.** A typo fix is a patch bump and no +deposit, so it leaves no trace here; a minor or major bump is a new deposit and +does. Otherwise the section fills with corrections nobody needs to know about, +and the ones that matter are lost in them. + +**The live page carries the current history; each deposited PDF carries the +history up to its own version.** That is correct rather than a defect, and it +is why nothing goes back to amend an older PDF -- a deposited copy is a fixed +document, and the version DOIs are what connect them. The concept DOI, with no +`.vN`, always resolves to the newest. + **A superseded guide becomes a new version, not a new article.** This is the editorial rule, and it is why the how-tos are deposited at all. The container instructions are the case in point: useful to know about, and going out of date. diff --git a/articles/running-underworld-in-a-browser/running-underworld-in-a-browser.md b/articles/running-underworld-in-a-browser/running-underworld-in-a-browser.md index a50eb2f..b2b5fe4 100644 --- a/articles/running-underworld-in-a-browser/running-underworld-in-a-browser.md +++ b/articles/running-underworld-in-a-browser/running-underworld-in-a-browser.md @@ -279,6 +279,16 @@ Three limits come with not running servers: +## History + +- **1.1.0** — 2026-08-31 · [10.6084/m9.figshare.33216996.v2](https://doi.org/10.6084/m9.figshare.33216996.v2) + Revised for house style and shortened by about a fifth, and the abstract + rewritten to say what the thing is for rather than list its parts. The + machinery described is unchanged: the container, the launcher, the workflows + and the URL all work exactly as they did in 1.0.0. +- **1.0.0** — 2026-08-11 · [10.6084/m9.figshare.33216996.v1](https://doi.org/10.6084/m9.figshare.33216996.v1) + First published. +
Comments
Discussion of these notes happens in GitHub Discussions, so it stays with the source and is searchable alongside it.
Read the discussionStart one
diff --git a/templates/article-template/ARTICLE.md b/templates/article-template/ARTICLE.md index 3865815..df737a5 100644 --- a/templates/article-template/ARTICLE.md +++ b/templates/article-template/ARTICLE.md @@ -113,3 +113,16 @@ deposited with the note, so the archived record carries working code. When a release breaks one, update it and publish a **new version** of the same deposit rather than a new note — the DOI already in circulation then resolves to the working notebook. + +## History + + diff --git a/tests/test_migration.py b/tests/test_migration.py index efea3c2..3712394 100644 --- a/tests/test_migration.py +++ b/tests/test_migration.py @@ -2416,3 +2416,40 @@ def test_the_deposit_reminder_asks_on_a_schedule_as_well_as_on_a_push(): # for every request left waiting. The two belong together. assert "gh pr list --state open" in src, \ "a scheduled reminder MUST skip what it has already asked about" + + +def test_a_redeposited_note_records_what_changed(): + """A note past its first deposit carries a `## History` section. + + Never changing a published note silently is the one thing every correction + policy agrees on, and the machinery cannot enforce the prose -- but it can + notice that a note has been deposited more than once and says nothing + about it. `archived_version` is the deposited version, so a `version` + ahead of `1.0.0` that has been deposited is a note that has moved. + """ + import re as _re + missing = [] + for meta_path in sorted((ROOT / "articles").glob("*/metadata.yml")): + text = meta_path.read_text(encoding="utf-8") + + def field(key): + m = _re.search(r"^%s:\s*(.+?)\s*$" % key, text, _re.M) + if not m: + return None + v = m.group(1).strip().strip('"').strip("'") + return None if v in ("null", "~", "") else v + + archived = field("archived_version") + # deposited, and at a version past the first + if not archived or archived == "1.0.0": + continue + slug = meta_path.parent.name + article = meta_path.parent / ("%s.md" % slug) + if not article.exists(): + continue + body = article.read_text(encoding="utf-8") + if not _re.search(r"^##+\s+History\s*$", body, _re.M): + missing.append("%s (deposited at %s)" % (slug, archived)) + assert not missing, ( + "these notes were deposited past 1.0.0 and carry no History section, " + "so a reader cannot tell what changed: %s" % ", ".join(missing)) From 41a14883d38414523c8050c42efa4d9b7183067e Mon Sep 17 00:00:00 2001 From: lmoresi Date: Mon, 7 Sep 2026 10:25:31 -0700 Subject: [PATCH 2/2] Bump the browser note to 1.1.1 for the History section Adding the section is a change to the note, so the version moves. It is a patch and is not redeposited, so it gets no History entry of its own -- only deposited versions do, or the section fills with self-reference. The outstanding report shows the note as ahead of its archival copy until the next deposit carries it, which is exactly what that line is for. Underworld development team with AI support from Claude Code --- articles/running-underworld-in-a-browser/metadata.yml | 2 +- .../running-underworld-in-a-browser.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/articles/running-underworld-in-a-browser/metadata.yml b/articles/running-underworld-in-a-browser/metadata.yml index 870b668..c1b3830 100644 --- a/articles/running-underworld-in-a-browser/metadata.yml +++ b/articles/running-underworld-in-a-browser/metadata.yml @@ -12,7 +12,7 @@ authors: orcid: 0000-0003-3685-174X affiliation: Australian National University publication_date: 2026-08-11 -version: 1.1.0 +version: 1.1.1 license: CC-BY-4.0 canonical_path: /running-underworld-in-a-browser/ legacy_paths: [] diff --git a/articles/running-underworld-in-a-browser/running-underworld-in-a-browser.md b/articles/running-underworld-in-a-browser/running-underworld-in-a-browser.md index b2b5fe4..47eb1a1 100644 --- a/articles/running-underworld-in-a-browser/running-underworld-in-a-browser.md +++ b/articles/running-underworld-in-a-browser/running-underworld-in-a-browser.md @@ -26,7 +26,7 @@ exports: template: ../../templates/pdf output: running-underworld-in-a-browser.pdf article_id: UWTN 2026-010 - article_version: 1.1.0 + article_version: 1.1.1 doi: 10.6084/m9.figshare.33216996 ---
Photo by James Lee / Unsplash