Introduce STAMPED as operational companion to FAIR - #26
Draft
yarikoptic wants to merge 4 commits into
Draft
Conversation
Add the DataLad JOSS publication (doi:10.21105/joss.03262) to references.bib and cite it on the first reference to DataLad in data_management.md. While there, fix the mangled markdown in the link label ([Dat*aLad] -> [*DataLad*]) so the intended italic-linked text actually renders. Co-Authored-By: Claude Code 2.1.204 / Claude Opus 4.7 <noreply@anthropic.com>
Plan the introduction of STAMPED principles (Self-containment, Tracking, Actionability, Modularity, Portability, Ephemerality, Distributability) as an operational-layer companion to the FAIR framework already covered in the book. Two-anchor placement: brief framing paragraph in introduction.md and deep subsection after FAIR in data_management.md, plus per-principle attachments in the chapters that already teach the practices (project_organization, workflows, sharing, HPC), a chapter ↔ principle ↔ checklist mapping table in extras.md, and the STAMPED preprint (Macdonald et al. 2026) added to references.bib. Decisions log (§8) captures Yaroslav's review pass; canonical BibTeX from `doiref` is in §10. Co-Authored-By: Claude Code 2.1.204 / Claude Opus 4.7 <noreply@anthropic.com>
Add the STAMPED framework [@macdonald:2026aa] as the operational-layer companion to the FAIR principles already covered in the book: - book/references.bib: add @misc{Macdonald:2026aa, ...} for the STAMPED preprint (doi:10.31222/osf.io/f3h82_v1), formatted to match the book's existing BibDesk-style @misc entries. - book/introduction.md: brief framing paragraph in the "Open science and reproducibility" section naming both FAIR and STAMPED, listing the seven STAMPED letters, and linking the interactive checklist. - book/data_management.md: deep subsection "STAMPED: an operational companion to FAIR" right after the FAIR Principles subsection, with one-sentence definition per principle, the MUST/SHOULD/MAY note, checklist link, and a co-author disclosure line. - book/workflows.md: one sentence at the end of the FAIR-inspired practices list mapping each listed practice to the relevant STAMPED principles. See docs/stamped-integration-plan.md for the design and decisions behind the placement. Co-Authored-By: Claude Code 2.1.204 / Claude Opus 4.7 <noreply@anthropic.com>
Weave the STAMPED principles into the chapters that already teach the
underlying practices, plus a chapters ↔ principles ↔ checklist mapping
table for readers who want to self-assess their own projects.
Per-chapter attachments:
- book/project_organization.md: name explicit environment specification
as STAMPED-Portability (§ "It needs to be portable"), and the code /
data separation with reachability from a common root as
STAMPED-Modularity + Self-containment (§ "Should code and data live
alongside one another?").
- book/data_management.md: name what DataLad provides — content-
addressed identification + code-driven provenance — as the
STAMPED-Tracking principle in practice.
- book/workflows.md: name the workflow-as-DAG pattern as
STAMPED-Actionability (§ Using a workflow engine); name running each
workflow inside a fresh container image as STAMPED-Ephemerality
(§ Reproducible environments with containers), with CI runners and
HPC per-job scratch dirs as exemplars.
- book/sharing.md: name depositing releases on Zenodo, Software
Heritage, container registries, and (for large data) git-annex /
DataLad-supported portals as STAMPED-Distributability; name
machine-readable metadata files (CITATION.cff, codemeta.json) as the
citation-and-identity end of STAMPED-Actionability.
- book/HPC.md: name explicit `module load python/3.14.2` as STAMPED-
Tracking (spelled-out runtime); name the container + scratch-dir
pattern as STAMPED-Ephemerality (HPC's natural exemplar).
- book/extras.md: a concise chapters ↔ STAMPED principles ↔
representative checklist items mapping table for readers using the
interactive checklist to self-assess. Item IDs verified against
stamped-checklist v0.1.0.
Wording derived verbatim / near-verbatim from Macdonald et al. 2026;
Ephemerality is framed git-independently ("stage in a temporary
location, run there, then discard") per docs/stamped-integration-plan.md
§8.3.
Co-Authored-By: Claude Code 2.1.204 / Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Sits on
Introduces developed by us (CON) the child of YODA -- STAMPED principles (Macdonald et al. 2026,
doi:10.31222/osf.io/f3h82_v1) (attn @asmacdo @CodyCBakerPhD and @leej3 for review) as the operational-layer companion to the FAIR framework already covered in the book.
Design, rationale, and per-chapter attachment strategy live in
docs/stamped-integration-plan.mdon this branch — please skim there rather than re-litigating in the PR conversation.Three commits:
Add STAMPED integration design doc— the plan file.Introduce STAMPED as operational companion to FAIR— bib entryintroduction.md+ deep subsectionafter FAIR in
data_management.md+ cross-reference in theFAIR-inspired list in
workflows.md.Attach STAMPED principles across book chapters— 1–3 sentenceattachments at existing seams in
project_organization.md,data_management.md(DataLad → Tracking),workflows.md(A + E),sharing.md(D + A),HPC.md(T + E), plus a chapters ↔principles ↔ checklist mapping table in
extras.md.Decisions to confirm before merge
docs/stamped-integration-plan.md? It servedas the design-and-decisions artifact for this PR (§8 records
the resolved review questions). Options:
- Keep in-tree as a "how we got here" record (drop from TOC
so it doesn't ship to readers — already the case).
- Kill with
git rm docs/stamped-integration-plan.mdas afixup commit before merge.
introduction.md, deep afterFAIR in
data_management.md) OK, or prefer single spot? Seeplan §8.4 for the alternatives considered.
data_management.md— adjust if you'd like different phrasing or kick it out entirely.book/extras.mdmapping table — leave as extras, or promote to a formal appendix inmyst.ymlTOC?Heads-up: upstream mystmd bug touching the Typst PDF path
While verifying the local PDF build I hit a genuine bug in
myst-to-typstthat turns the STAMPED bullets (**S**elf-containment,**T**racking, …) into invalid Typst syntax, somake build-pdffails at the Typst export step. The LaTeX PDF export is unaffected. Root cause + fix + minimal reproducer filed upstream asOptions for this PR:
LaTeX PDF path both work.
myst.ymlin a separate PR (removesa broken target from the default build without changing content).
--template plain_latex_bookinbook/Makefilein aseparate PR (same effect, keeps the Typst target configured for the
day it works).
**E**mphasisfor now in that spot.Happy to open whichever of the second/third you prefer, but wanted
your read first — I don't want to change how you build the book as a
side effect of this PR.