From dce7f995e8e11a37ba640f51e5f8626a2c14b89b Mon Sep 17 00:00:00 2001 From: Tim Dennis Date: Wed, 23 Sep 2026 12:54:07 -0700 Subject: [PATCH] Zenodo Sandbox caveats callout; cffinit as an equal path for CITATION.cff - Release episode: 'What to expect from Zenodo Sandbox' callout (separate login, 10.5072 DOIs don't resolve on doi.org, records may be cleaned, slow or missed releases) with a fallback checklist and an instructor note on keeping a prepared repo ready - Badge and CITATION.cff examples now show Sandbox-shaped DOIs, with the production shape noted, fixing the conflict with the sandbox-DOI warning - CITATION.cff episode: Option A (GitHub template) and Option B (cffinit form, step by step) presented as equal choices --- episodes/adding-citation-file.md | 29 ++++++++++++------ episodes/making-software-citable.md | 46 ++++++++++++++++++++++++----- 2 files changed, 58 insertions(+), 17 deletions(-) diff --git a/episodes/adding-citation-file.md b/episodes/adding-citation-file.md index de80754..925f3b0 100644 --- a/episodes/adding-citation-file.md +++ b/episodes/adding-citation-file.md @@ -81,7 +81,12 @@ If you have ever edited a repository record, filled in a Dublin Core field, or t ## How to Create a CITATION.cff File -You will do this entirely in GitHub's web interface, in your fork. No terminal required. GitHub has this built in: name a new file `CITATION.cff` and it hands you a starter template to edit. +You will do this entirely in the browser, in your fork. No terminal required. There are two good ways to write the file, and either one is fine: + +- **Option A: GitHub's template.** Name a new file `CITATION.cff` and GitHub offers a starter template to edit. Quickest if you are comfortable editing a few lines of YAML. +- **Option B: the cffinit form.** Fill in a web form that checks your entries as you go, then paste the result into GitHub. The safer choice if YAML is new to you, or if the file has many authors. + +Both end the same way: a `CITATION.cff` in the root of your repository, committed to `main`. ::::::::::::::::::::::::::::::::::::: instructor @@ -91,7 +96,7 @@ Learners may try to perfect authorship, contributor roles, or author order. For :::::::::::::::::::::::::::::::::::::::::::::::: -### Create the file on GitHub +### Option A: Create the file from GitHub's template In your fork of `software-demo`: @@ -120,21 +125,27 @@ date-released: 2026-07-05 url: "https://github.com/YOUR-USERNAME/your-repository-name" ``` -::::::::::::::::::::::::::::::::::::: callout - ::::::::::::::::::::::::::::::::::::: instructor ### YAML recovery path -If more than a few learners hit YAML indentation errors, switch the whole room to cffinit rather than debugging individual whitespace mistakes. The goal is citation metadata, not YAML mastery. cffinit validates as they type and produces a file they can paste. +If more than a few learners hit YAML indentation errors, switch the whole room to Option B rather than debugging individual whitespace mistakes. The goal is citation metadata, not YAML mastery. You can also teach Option B from the start: it works well as the main demo. :::::::::::::::::::::::::::::::::::::::::::::::: -### Prefer a guided form? Use cffinit +### Option B: Fill in the cffinit form -[**cffinit**](https://citation-file-format.github.io/cffinit/) is a web wizard that walks you field by field and validates as you type. It is worth using when your metadata is more involved: many authors, a `preferred-citation` for an associated paper, keywords, or a license you want recorded precisely. Fill out the form, copy the generated file, and paste it into the same `CITATION.cff` you create on GitHub. More on the format: . +[**cffinit**](https://citation-file-format.github.io/cffinit/) is a free web form from the Citation File Format project. It walks you through the file one screen at a time and flags mistakes as you type, so you never touch the YAML directly. -:::::::::::::::::::::::::::::::::::::::::::::::: +1. Open and click **Create**. +2. **Start:** choose **Software**, enter the title (`Biodiversity Analysis Toolkit`), and leave the message blank to use the default. +3. **Authors:** add each author. Add ORCIDs if you have them. +4. **Identifiers:** skip for now. You will add a DOI in the next episode. +5. Click **Finish** to jump to the end. The remaining screens (abstract, keywords, license, version) are optional; come back to them any time. +6. Copy the file: click **Copy to clipboard** on the preview, or **Download**. +7. Back on GitHub, in your fork: **Add file → Create new file**, name it exactly `CITATION.cff`, paste, and click **Commit changes…** to `main`. + +cffinit also pays off when a file gets complicated: many authors, a `preferred-citation` for an associated paper, keywords, or a license you want recorded precisely. More on the format: . A finished file looks like this: @@ -316,7 +327,7 @@ Typical missing pieces include: Steps: -1. Create CITATION.cff. +1. Create CITATION.cff, with GitHub's template (Option A) or the cffinit form (Option B). 2. Add at least: title, author(s), and message. 3. Commit and refresh to see GitHub’s citation panel. diff --git a/episodes/making-software-citable.md b/episodes/making-software-citable.md index f3d5f30..bd34fe0 100644 --- a/episodes/making-software-citable.md +++ b/episodes/making-software-citable.md @@ -148,7 +148,7 @@ Use `sandbox.zenodo.org`, not production Zenodo. Real Zenodo records and DOIs ar :::::::::::::::::::::::::::::::::::::::::::::::: -To practice minting a DOI without polluting the permanent scholarly record, we will use **Zenodo Sandbox**. It works exactly like the real Zenodo but is for testing. +To practice minting a DOI without polluting the permanent scholarly record, we will use **Zenodo Sandbox**. It walks you through the same steps as the real Zenodo, but it is a test site, with a few differences worth knowing before you start. ::::::::::::::::::::::::::::::::::::: caution @@ -158,6 +158,34 @@ Real Zenodo records are permanent: a published DOI cannot be deleted. Use the morning of the workshop. + +:::::::::::::::::::::::::::::::::::::::::::::::: + ::::::::::::::::::::::::::::::::::::: challenge ### Predict: what happens when you publish? @@ -205,23 +233,25 @@ Zenodo detects the release, downloads and archives a snapshot of the repository - Zenodo automatically detects your new release - Creates an archived snapshot -- Assigns a permanent DOI -- Wait a few minutes for processing +- Assigns a DOI (on real Zenodo it is permanent; in the Sandbox it starts with `10.5072` and is for practice) +- Wait a few minutes for processing. Nothing after five minutes? See "What to expect from Zenodo Sandbox" above **Step 5: Add DOI badge to your README** -- Copy the DOI badge from your Zenodo record -- Add it to the top of your README: +- Copy the DOI badge Markdown from your Sandbox record page (the DOI badge on the right side of the record) +- Add it to the top of your README. A Sandbox badge looks like this; note that it links to the Sandbox record, because Sandbox DOIs do not resolve on doi.org: ```markdown -[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.123456.svg)](https://doi.org/10.5281/zenodo.123456) +[![DOI](https://sandbox.zenodo.org/badge/DOI/10.5072/zenodo.123456.svg)](https://sandbox.zenodo.org/records/123456) ``` +- On real Zenodo the badge uses your `10.5281` DOI and links to `https://doi.org/10.5281/zenodo.123456` **Step 6: Update your CFF file with your DOI** - Add the DOI to your `CITATION.cff`: ```yaml -doi: 10.5281/zenodo.123456 +doi: 10.5072/zenodo.123456 ``` +- This is fine in your practice fork. For real software, the `doi` comes from a real Zenodo deposit and starts with `10.5281` **Result:** You now have LICENSE, CITATION.cff, and DOI. @@ -245,7 +275,7 @@ This point is subtle and important, so slow down. Say: "GitHub is the live worki ### If Zenodo can't see your repository -Zenodo only lists repositories you have admin rights on. For an organization repo, an org owner may need to approve Zenodo's access first; for this exercise, forking under your personal account avoids the problem entirely. (Keep the sandbox rule in mind too: a `10.5072/...` sandbox DOI is for practice, never for a paper or a real `CITATION.cff`.) +Zenodo only lists repositories you have admin rights on. For an organization repo, an org owner may need to approve Zenodo's access first; for this exercise, forking under your personal account avoids the problem entirely. (Keep the sandbox rule in mind too: a `10.5072/...` sandbox DOI is for practice, never for a paper or for the `CITATION.cff` of software you are actually releasing.) ::::::::::::::::::::::::::::::::::::::::::::::::