Instructor Notes

Lesson Overview

This lesson teaches researchers how to make software citable and discoverable. The core arc is:

Sharing → License → CITATION.cff → Release/DOI → Metadata

The environment management episode (pixi) is optional and sits after the release/DOI episode in the default lesson order. Decide before your workshop which track you are running.

Choosing a Track

Full track (~3.5 hours)

All episodes in order. Suitable when reproducibility and environment management are part of the workshop goals, or when your audience includes researchers who maintain code others need to run.

Citation-focused track (~2.5 hours)

Skip the pixi episode entirely. Suitable for a shorter workshop or when learners just want their code cited, not necessarily reproduced. The FAIR4RS checklist in the wrap-up still works; simply omit the environment/interoperability row or note it as “future work.”

The Branch Structure and Pixi

The demo repository (UC-OSPO-Network/software-demo) uses numbered branches that reflect the original episode order, where pixi came before the citation file:

01-start → 02-license → 03-pixi → 04-citation → 05-release → 06-metadata

The lesson episode order has been updated so pixi now comes after the release/DOI episode. This creates a mismatch between branch numbers and lesson order that instructors need to manage.

Full track: branch navigation

Lesson episode Branch to check out
Sharing Software 01-start
Open Source License 02-license
Adding a CITATION.cff File 02-license → work done live, result is 04-citation
Making Your Software Citable 04-citation → work done live, result is 05-release
Managing Environments (pixi) 03-pixi (see note below)
Improving Metadata 05-release → work done live, result is 06-metadata

Note on pixi branch: 03-pixi sits earlier in the demo repo history than 04-citation, but that’s fine. Learners are just exploring it to see what a locked environment looks like; they don’t need to build on it. Have them check out 03-pixi to follow along, then return to 05-release before the metadata episode.

Citation-focused track: branch navigation

Lesson episode Branch to check out
Sharing Software 01-start
Open Source License 02-license
Adding a CITATION.cff File 02-license → result is 04-citation
Making Your Software Citable 04-citation → result is 05-release
Improving Metadata 05-release → result is 06-metadata

Important: 04-citation and later branches contain pixi files (pixi.toml, pixi.lock) even though learners haven’t done the pixi episode. Acknowledge this briefly: “You’ll see some pixi files in the repo; those are from an optional episode on environment management. You can ignore them for now.”

Common Sticking Points

GitHub “Cite this repository” button not appearing Learners need to commit the CITATION.cff file to the default branch and refresh. GitHub may take a minute to parse it. If it doesn’t appear, check that the file is in the root of the repository and named exactly CITATION.cff.

Zenodo Sandbox login Use sandbox.zenodo.org, not the real zenodo.org. Learners who accidentally create records on the live site cannot delete them. Warn the group before this step.

YAML indentation errors in CITATION.cff Direct learners to the cffinit web tool (https://citation-file-format.github.io/cffinit/) rather than hand-editing YAML. This eliminates most formatting errors.

Pixi not installed Pixi is optional and learners do not need it installed to complete the citation-focused track. If running the full track, verify pixi installation during setup. The pixi episode callout already marks it optional so learners who skip it can rejoin cleanly.

Introduction: The "Works on My Machine" Trap

Instructor Note

This concrete error message resonates with learners who have experienced dependency issues. Pause here to ask: “Has anyone experienced this problem?” This builds connection and motivation.


Sharing Research Software Effectively

Preparing the Demo Repository

To demonstrate the “before and after” states of research software, use the provided automation script:

  1. Locate the script: create_demo_repo.sh is in the root of the lesson repository.
  2. Run the script: Move it to a non-git directory (e.g., ~/projects/) and run bash create_demo_repo.sh.
  3. Progression: The script creates branches (01-start through 06-metadata). You can git checkout these branches during the lesson to show incremental progress.
  4. GitHub Hosting: We recommend pushing this generated repository to your GitHub account before the workshop so learners can follow along online. Commands for pushing are printed at the end of the script.

Use progressive disclosure by showing only the top-level structure of the demo repository first.
If learners are new to GitHub, you may display two contrasting examples:

  • a sparse, hard-to-understand repo (checkout branch 01-start)
  • a clear, well-documented repo (checkout branch 06-metadata)

Choosing an Open-Source License

Adding a CITATION.cff File

Instructor Note

Show learners what the citation panel looks like on a GitHub repository that already has a CITATION.cff file. This gives them a clear target and reduces cognitive load.

Reassure learners that a tiny file is fine. They can refine it later as their software matures.


Making Your Software Citable

Instructor Note

Some learners may feel anxious about creating a DOI.
Reassure them that:

  • a DOI is not required for citability
  • Zenodo is free and widely used
  • they can watch the demo and complete the steps later

Instructor Note

Critical: Ensure learners use sandbox.zenodo.org. Real DOIs cannot be deleted.


Managing Reproducible Environments with pixi

Teaching this optional episode

This episode appears after the release/DOI episode in the lesson order. The demo repository branch 03-pixi sits earlier in the repo history (between 02-license and 04-citation), so the branch number and lesson position don’t match, which is expected.

How to handle the branch:

Have learners check out 03-pixi to follow along. They are exploring it as a standalone example, not building on it. After this episode, direct them back to 05-release to continue with the metadata episode.

BASH 

# During this episode
git checkout 03-pixi

# After this episode, return here to continue
git checkout 05-release

If skipping this episode: Learners who went from 02-license straight to 04-citation will already have pixi files in their repo (they were baked into the branch). Acknowledge this briefly when they encounter pixi.toml or pixi.lock in the metadata episode: “Those files are from the optional environment management episode; you can leave them as-is.”

Pixi not installed? Learners can follow the concepts without a working pixi installation. The key idea is that a lockfile pins exact dependency versions. That’s the transferable lesson, not the tool itself.


Improving Metadata and Discoverability

Instructor Note

Encourage learners to compare well-described repositories with sparse ones.
Highlight how even small metadata additions increase visibility in GitHub search, Zenodo indexing, and DataCite services.


Wrap-Up and Reflection

Instructor Note

Give learners a few minutes of quiet reflection, then facilitate a group discussion. Invite volunteers to share a step they plan to take next.