dandi / dandi/example-notebooks

Mint DOIs for notebook groups from the image workflow

Open
#202 7 comments 0 reactions 3 assignees Claimed by @asmacdo View on GitHub
Dominant language
Jupyter Notebook
Stars
9
Forks
20
Avg merge
2h 9m
Merged PRs (30d)
29

Description

Every notebook group is now published as a verified container image, and the blog post makes the case for the collection as a venue for executable research artifacts. What is missing is a citable identifier for each artifact. This issue proposes minting a DOI per notebook group on Zenodo, automatically, from the same workflow that publishes the image.

## What Gets a DOI

One concept DOI per notebook group (the unit that already maps to one image), with a new version DOI whenever the group changes. The image is recorded inside each version as its executable form rather than getting its own DOI, since the notebook is the intellectual object and the image is its frozen environment.

## Authorship Comes from an Opt-In CITATION.cff

A DOI needs creators, ideally with ORCIDs, and nothing structured exists per notebook today (a survey found zero authorship metadata in any notebook or README). Proposal: a `CITATION.cff` in the group directory, alongside `requirements.in`, carrying authors with ORCIDs, a title, the license, and the paper DOI under `references`. Only groups with one get a DOI, so nothing is minted without real authorship. This also gives GitHub's "Cite this repository" button something to show.

## When Minting Happens, and When It Does Not

The step runs at the end of the merge job, only when a manifest was actually published. Versioning is keyed to the full build hash, which covers the notebooks, pins, helper fetches, the CITATION.cff, and the Dockerfile, so each DOI version corresponds to exactly one published image digest. A change to a group's own content mints a new version automatically. Rebuilds caused by tooling changes (Dockerfile, base image, system libraries) rebuild every group, and those mint new versions only when the run is dispatched with an explicit `mint` flag, so an environment bump is a deliberate release rather than a side effect. Old image digests are never deleted, so earlier DOI versions keep resolving to exactly what they described. If the newest Zenodo version already carries the current build hash, the step exits. Existing records are found by searching Zenodo for a keyword of the form `dandi-notebooks:`, so no state is written back to the repo.

## What a Record Contains

The verified container image itself, deposited as an OCI image archive (one file holding both the amd64 and arm64 images, 3 to 4 GB, within Zenodo's 50 GB per-record limit), so the executable form persists with the record and does not depend on the GitHub Container Registry staying up. Alongside it: the notebooks, `requirements.in`, `README.md`, `CITATION.cff`, the resolved pin list, and an `image.json` recording the registry reference, manifest digest, tags, and commit, so the deposited archive can be matched to what the registry served. Related identifiers link the dandiset's published DOI (DANDI exposes `10.48324/dandi./` for published versions; drafts get the URL instead), the paper DOI, and the GitHub tree at the commit. The index page would show a DOI badge next to the Colab and docker badges, looked up the same way it checks GHCR today.

## Account, License, and Rollout

A DANDI-owned Zenodo account provides the token as a repository secret. The whole flow is validated against sandbox.zenodo.org first (create, no-op rerun, new version on change) before the production token is added. Default record license is Apache-2.0 to match the repository, overridable per group in CITATION.cff. Pilot on one group, then invite contributors to add CITATION.cff files.

## Open Questions

1. Depositing the image archive means roughly 3 to 4 GB per version across a few dozen groups. Zenodo allows it, but it is worth a word with them about expected volume before the first production mint.
2. Is there a DANDI Zenodo community these should be collected under?
3. For existing notebooks, who supplies authorship: the contributors who wrote them, the dataset authors, or both? The dataset's DANDI contributors (with ORCIDs) are machine-readable and could be offered as a default for review.
4. Relation types for the dandiset and paper links: `isSupplementTo` seems right for both, but opinions welcome.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.