Skip to content

Releases

v1.6 — citing these notes, and naming their own sources

Choose a tag to compare

@rdicosmo rdicosmo released this 24 Sep 12:01

Two new appendices, and three values the build now derives instead of being told.

Appendix I, How to cite these notes. Cite the HAL record without a version
number, https://hal.science/hal-05734828, which always resolves to the latest
version; cite the versioned record, the release tag or the source SWHID when the
reference supports a claim. Includes the plain-text and BibTeX forms, and the
reason the HAL PDF and the release PDF are different digital objects.

Appendix J, How these notes name their own sources. An intrinsic identifier
is a hash of content, so a file cannot name itself. It can name the sources it
was built from, provided the stamp is derived rather than declared and kept out
of the tree it names. The appendix explains the mechanism and invites the reader
to recompute it with make swhid.

Derived, not declared. The version now comes from the annotated tag via
git describe, so the tag is the single source of truth. The date comes from the
commit rather than the clock, so two people building this revision get the same
title page. The source SWHID is computed offline from git archive HEAD into the
git-ignored swhid.tex. The build stamps a clean tree only.

Title page gains the affiliations, homepage and ORCID.

Source tree of this release:

swh:1:dir:8245d19766173d59c2847826ade1128f4f4fd8b1;
  origin=https://github.com/rdicosmo/source-code-of-science;
  visit=swh:1:snp:59e699dda0e3844b41090096f0a04a9e02b2f2da;
  anchor=swh:1:rel:c15603ebc97f8580a9b4bcf27f9fcb02f3be8b7b

v1.5 — Archie, and where these drawings came from

Choose a tag to compare

@rdicosmo rdicosmo released this 15 Sep 20:52

Appendix H, Archie, and how these illustrations were made, gives these notes the account of their own artefacts that a note about provenance owes.

It records the mascot and why he is an elephant: long memory, the patient multi-decade custodianship an archive actually is, and a character who can act out a chapter's mechanism instead of decorating it. It says why the name Archie (archivist, archive, and the 1990 McGill search engine, the first tool built to find what had been stored), and which names were rejected and why.

It discloses, plainly, that all ten plates are AI-generated with Google Gemini image generation, directed and selected by the author, and it gives the method: the consistency chain that keeps one character across ten drawings, and the fixed style anchor prepended to every prompt.

It then says what each plate asserts, and keeps the three production failures worth recording, ending on the one that is this book's own thesis turned back on its own production: a name, a prompt or a filename describes an artefact; only the artefact is evidence.

80 pages to 84. No other text changed.

Archived source for this release

swh:1:dir:769f7afe6cc52fe86bd63d35cb68e7513874e2fd;origin=https://github.com/rdicosmo/source-code-of-science;visit=swh:1:snp:b8715018e8f7ffab19b3f8a88fcd036fd2020ca8;anchor=swh:1:rev:7f22576697b3ee89eb96ac11839f724fe7db91b0

A pristine, byte-stable copy of the PDF is also at https://dicosmo.org/Articles/2026-source-code-of-science.pdf.

v1.4 — artifact evaluation, the way it actually works

Choose a tag to compare

@rdicosmo rdicosmo released this 09 Sep 01:30

Artifact evaluation, the way it actually works.

Appendix G used to lead with a local git archive computation and treat the archive as a camera-ready afterthought. That is backwards for the case that actually occurs: most venues evaluate artifacts after acceptance, the artifact is a public repository on a public forge, and the identifier can simply be read off the archive.

What changed

  • §G.2 — the common case. Archive the repository (the UpdateSWH extension first, then Save Code Now, then a forge webhook), copy the qualified dir SWHID from the Permalinks tab, hand it over. The author computes nothing — so the working-copy hazard cannot bite on the common route.
  • §G.3 — blind review. Same procedure; share only the part before the first ;. A core SWHID carries no origin, author, date or commit, so archiving at submission is safe. This replaces the earlier advice to defer archival, which was over-cautious rather than wrong. The one residual disclosure — a public row in the save-request list — is named rather than glossed.
  • §G.7 — reviewers: there is nothing to check. The archive retrieves the object by its hash, so asking a reviewer to re-derive the identifier they used to fetch the artifact tests their tar command, not the artifact. The two computations that do occur are attributed properly: the reviewer only when handed a bundle instead of an identifier, and the chair once, at camera-ready.
  • Figure G.1 — two real captures of one directory hash in the archive, qualified and core, showing the identical breadcrumb and exactly what the qualifiers add.
  • Archival procedure now points at Software Heritage's own how-to; this repository's docs/HOWTO-artifact-swhid.md keeps only what artifact evaluation adds.
  • Chapter 6's double-blind hands-on told students to run swhid dir ./ on a checkout — the exact hazard the notes warn about. Fixed.

Source

swh:1:dir:10fe8f4e74ad2c98d86e88f80bc233b6fb9b229d;origin=https://github.com/rdicosmo/source-code-of-science;anchor=swh:1:rev:0489cd4d9520106e64728e4ee10d0751bd39fe1d

Verified four ways before release: local clean export, git rev-parse HEAD^{tree}, the directory the archive holds for that revision, and the archived visit (full, snapshot swh:1:snp:202524be96fe40227d72826e397ef0bc70e1d79b) all give 10fe8f4e….

80 pages. CC-BY-4.0.

v1.3.1 — corrected SWHID guidance

Choose a tag to compare

@rdicosmo rdicosmo released this 08 Sep 15:23

⚠️ Superseded for artifact evaluation — use v1.4.

Appendix G in this release tells authors not to archive before acceptance under double-blind review, and asks reviewers to verify the artifact by recomputing its identifier. Neither is necessary:

  • a core SWHID carries no origin, author, date or commit, so archiving at submission is safe — share only the part before the first ; and restore the qualifiers at camera-ready (v1.4 §G.3);
  • the archive retrieves an object by its hash, so asking a reviewer to re-derive the identifier they used to fetch the artifact tests their tar command, not the artifact (v1.4 §G.7).

The guidance here yields correct identifiers by a clumsier route — this is a supersession, not an erratum. Everything else in this release stands.


A correction release. If you are following the artifact-evaluation guidance in v1.3, please use this version instead.

What was wrong

Appendix G told authors to compute an artifact's identifier by running swh identify --type directory on a working copy. That hashes whatever is on disk — .git/, build output, caches, editor droppings — so it cannot match the tree Software Heritage archives from version control. Author and reviewer would both have believed they had verified something. An instruction that silently yields the wrong identifier is worse than an incomplete one: it destroys the single property the identifier exists to provide.

Demonstrated on this repository, at the commit released as v1.3:

swh identify .              -> swh:1:dir:3c96945d...   (polluted checkout)
clean git archive export    -> swh:1:dir:a53cbfce...
git rev-parse HEAD^{tree}   -> a53cbfce...
the archive's own directory -> a53cbfce...

Three independent sources agree; the checkout disagrees with all of them — and yields a different wrong answer at different times.

Two further errata, both in published text: --permissions-source does not exist in swh identify (the book cited it twice; --type accepts only auto|content|directory|origin|snapshot), and Appendix A claimed swh identify . on a checkout returns a rev SWHID — it returns a dir hash of the polluted tree.

What changed

Appendix G now carries the mandate and the invariant — the identifier always names a clean tree, never a live checkout, and for git that is exactly git rev-parse <commit>^{tree} — plus the two-phase rule: clean export before archival (the only option under double-blind), the archive's Permalinks value primary after, and their coincidence as the end-to-end check. The reviewer section now states honestly what a tarball does and does not permit.

Everything version-, tool- and platform-dependent moved to a new docs/HOWTO-artifact-swhid.md, maintained in this repository and referenced by path rather than pinned — it is expected to move as tooling does. Every command in it was executed as written; anything that could not be tested is labelled untested.

Archived source

swh:1:dir:7f7632c96529ac80f91a658fe1f5b38aab189787;origin=https://github.com/rdicosmo/source-code-of-science;visit=swh:1:snp:3a6a6fb5731051810bfdee590f8afed6def8771f;anchor=swh:1:rev:1be68205

Computed with the corrected recipe — clean export, self-checked against git rev-parse HEAD^{tree} — and verified equal to the directory the archive holds.

v1.3 — illustrated edition

Choose a tag to compare

@rdicosmo rdicosmo released this 07 Sep 20:18

⚠️ Superseded — use v1.4. Two rounds of correction apply to this release.

  • SWHID guidance (cookbook and handouts), corrected in v1.3.1: swh identify has no --permissions-source flag, and pointing it at a working copy hashes .git/, build output and editor droppings along with the artifact.
  • Appendix G, artifact evaluation, rebuilt in v1.4: this release tells authors not to archive before acceptance under double-blind review, and asks reviewers to recompute the identifier. Neither is necessary — a core SWHID discloses no origin, author or date, and the archive retrieves by hash, so a reviewer has nothing to check. See v1.4 §G.3 and §G.7.

Everything else in this release stands.


The illustrated edition. Every chapter now opens with a pen-and-ink plate of Archie, the elephant archivist, followed by a short summary of what the chapter argues; the title page carries a frontispiece — a tree growing out of an open book, its leaves made of files.

What changed

Illustrations. Nine chapter-head plates plus a frontispiece, at full measure. A provenance record — the mascot's design, every prompt, the failed iterations, and an AI-generation disclosure — is kept with the source images.

Refreshed evidence. Archive counters updated to the 2026-09-08 baseline (29.5 billion source files, 441 million projects). The graph figures are now cited: 58,675,740,295 nodes and 1,101,018,460,510 edges, from the publicly readable s3://softwareheritage/graph/2026-06-04/compressed. Figure 3.1's counters are typeset rather than shipped as unreadable pixels — the smallest text on that page goes from roughly 3 pt to 11 pt.

New Appendix G — a model artifact-evaluation section. Paste-ready text for programme chairs, an eight-step author walkthrough and a six-step reviewer procedure, a mapping onto the existing ACM badge vocabulary, and the questions a chair actually asks. Synthesised from 34 artifact-evaluation guidelines, written to be additive: it removes no DOI and displaces no deposit.

Typography. Key takeaways are now cut into the text block rather than parked in the margin; the accent colour is reserved for structure; the title page uses the book's display sans.

Archived source

swh:1:dir:a53cbfce5692dd6b375af39965089e3a4301905a;origin=https://github.com/rdicosmo/source-code-of-science;visit=swh:1:snp:b3e19812a3c2461aa3d5866ba49a1f24f1f4b765;anchor=swh:1:rev:d7263e66ea4d96ba28df3ef5af3700bc21327434

The archived directory was verified against a local git archive HEAD computation before this release was cut.

v1.2.3 — HAL edition

Choose a tag to compare

@rdicosmo rdicosmo released this 01 Sep 16:32

The self-referential SWHID colophon was removed and parked in annex-colophon.tex (not built). It printed the note's own archived-source SWHID and had the reader recompute it; two problems made it more confusing than instructive:

  • a document cannot contain its own SWHID, so the printed identifier named the source directory — which builds an unstamped sibling of the PDF in hand, a gap that took several paragraphs to excuse;
  • the capstone used git archive HEAD, but HEAD drifts past the release the identifier names, so a reader on any later commit gets a mismatch with no way to tell whether the note or their checkout is wrong.

The note's subject — archive the source, cite it with a SWHID — is taught in the body (Chapters 4–5) rather than enacted on the note itself. This is the copy deposited in HAL. No stamped PDF: the release asset is the plain build.

Archived source (qualified SWHID):
swh:1:dir:e6b30188eec828a81ad41fb7a9515e73c23b1a6d;origin=https://github.com/rdicosmo/source-code-of-science;visit=swh:1:snp:f61c36c639a93ef37bae76edab9ace7fc34b6c78;anchor=swh:1:rev:f54ceba5475542bcc859d1bb286090c457d8a5a1

v1.2.2 — HAL edition (colophon sharpened)

Choose a tag to compare

@rdicosmo rdicosmo released this 18 Aug 19:55

A review of the v1.2.1 colophon (by Fable) found it right on every byte-level fact but imprecise where it assigned meaning to those facts. v1.2.2 fixes that.

  • The lesson, sharpened. Byte-exactness is the right granularity for source code — a one-character change can change what a program does — and the wrong one for documents: a PDF, its PDF/A conversion, a PostScript export, or a rebuild under a newer TeX Live are byte-different objects that are the same document to every reader. The cover page is no longer lumped in as "another byte variant": prepending one produces a different document for the reader, which is the counterexample that defines the boundary.
  • Capstone corrected. A match verifies the archived source, not "the document you are reading" — the source builds the unstamped sibling PDF, not the stamped PDF in hand. Step 3 now says to ignore everything after the first ; (the stamp carries origin;visit;anchor), and a clone step is added since a PDF reader has no checkout.

This is the exact PDF deposited in HAL. Its colophon carries the qualified SWHID of the archived source:
swh:1:dir:2f0cd063b20c3dd4d4b87a14d624290f45da6fe3;origin=https://github.com/rdicosmo/source-code-of-science;visit=swh:1:snp:e61716bf138b50ebd9607e6db3b9a7a02366a2df;anchor=swh:1:rev:797170259c947b075a4185c22f978add131b0785

A pristine, byte-stable rendering also lives at https://dicosmo.org/Articles/2026-source-code-of-science.pdf.

v1.2.1 — HAL edition

Choose a tag to compare

@rdicosmo rdicosmo released this 18 Aug 10:05

Colophon caveat for cover-page repositories (HAL) + a pointer to the pristine, byte-stable copy.

  • HAL and other repositories prepend an institutional cover page, producing a different digital object whose bytes — and any cnt: SWHID over them — no longer match this rendering. The source-directory SWHID in the colophon is unaffected (it names the canonical source tree, not the PDF).
  • The colophon now says so, points to the pristine copy at https://dicosmo.org/Articles/2026-source-code-of-science.pdf, and draws the lesson: intrinsic identifiers are exact for source code (canonical form) and ill-suited to rendered documents (no canonical byte-form).

This is the exact PDF deposited in HAL. Its colophon carries the qualified SWHID of the archived source:
swh:1:dir:79a540e975cbebcbef6cdc0b4a5225f04da45e36;origin=https://github.com/rdicosmo/source-code-of-science;visit=swh:1:snp:2a22d697f0c12aa1517128d9e4ac19efbc5ef042;anchor=swh:1:rev:3578aba7f5ab0ee8950e323794d45124ff1c8c5c

v1.2 — The Source Code of Science (memoir edition)

Choose a tag to compare

@rdicosmo rdicosmo released this 23 Jul 22:01

The memoir-typeset edition of The Source Code of Science.

What's new since v1.1

  • New book design — moved to the memoir class: elegant chapter openers (a large accent numeral floating toward the wide margin, hairline accent rule), refined vertical rhythm and page layout.
  • Release version now shown on the title page and in the footer (this is v1.2), alongside the build-time git hash.
  • DOI-resolution figure now numbers all four steps of the resolution (browser → resolver → browser → publisher → browser).
  • Closing call to action set as a display pull-quote.

Archived in Software Heritage

This release is archived, and the note verifies itself:

The attached PDF

source-code-of-science-swhid.pdf is the release build, stamped in its colophon with the qualified SWHID of its own archived source (built after archiving, so it is deliberately not part of the hashed source tree). Its footer records the version and the build-time git state.

v1.1 — The Source Code of Science (restyled)

Choose a tag to compare

@rdicosmo rdicosmo released this 23 Jul 20:55

Restyled build of The Source Code of Science.

What's new since v1.0

  • Classier layout — titlesec chapter openers (large accent numeral, hairline rule), accent section numbers, and fancyhdr running heads.
  • Provenance footer on every page — author · title · CC-BY-4.0 · build date · git hash of the source at build time.
  • DOI-resolution figure redrawn to show the two bidirectional register lookups and the numbered resolution order.
  • Page-fill tuning (float packing + ragged bottom).

Archived in Software Heritage

This release is archived, and the note verifies itself:

The attached PDF

source-code-of-science-swhid.pdf is the release build, stamped in its colophon with the qualified SWHID of its own archived source (built after archiving, so it is deliberately not part of the hashed source tree). Its footer records the build-time git state.