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/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 a50eb2f..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
@@ -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))