Summary and Schedule

Diagram titled "Core Elements of Citable and Discoverable Research Software": six hexagons in two groups. Blue (Citable): Release and DOI, CITATION.cff, and License. Green (Discoverable): Metadata and Topics, README and Docs, and Public Archive.
Diagram titled “Core Elements of Citable and Discoverable Research Software”: six hexagons in two groups. Blue (Citable): Release and DOI, CITATION.cff, and License. Green (Discoverable): Metadata and Topics, README and Docs, and Public Archive.

About This Lesson

This lesson teaches the practical steps that make research software citable, discoverable, and reusable: choosing an open-source license, adding a CITATION.cff file, minting a DOI with a versioned release, and improving the metadata that helps people find and credit the software. An optional final episode covers reproducible environments with pixi. Together these steps map to the FAIR principles for research software (FAIR4RS).

It is written first for library, OSPO, and scholarly-communications staff and other research-support professionals who help researchers make software count as a scholarly output. Each episode also carries a “Supporting others” thread for that consulting work. Researchers who write code and want to make it citable themselves will find the same steps apply directly to their own repositories.

Learners work in the browser, making small, high-value improvements to a real GitHub repository, and leave with both a citable project and a reusable way to advise others.

Callout

How This Lesson Works

You’ll work in your web browser, in your own fork of a small demo repository. Each episode adds one piece to your fork: a license, a citation file, a release with a DOI, then richer metadata. By the end you’ll have a complete, citable repository you built yourself.

The upstream repository keeps a set of view-only reference branches (after-license, after-citation, after-release, after-metadata) showing the target state after each episode. If you fall behind or want to check your work, open the matching branch in GitHub’s branch dropdown and compare.

The only episode that needs software installed on your computer is the optional pixi episode at the end. Everything else runs in the browser. See Setup to get ready.

Learning Objectives

After completing this lesson, learners will be able to:

  • explain why research software should be cited and attributed.
  • add and validate a CITATION.cff file in a GitHub repository.
  • choose and apply an appropriate open-source license.
  • improve software discoverability through documentation and metadata.
  • understand how packaging tools like pixi can support usability and reproducibility.
  • describe how these practices support FAIR principles for research software.
  • identify small, high-value improvements that increase the visibility and impact of their software.
Prerequisite

Prerequisites

For the core lesson you need only a GitHub account and a web browser. Before beginning, it helps to be able to:

  • navigate GitHub in a web browser (view and edit files, open issues).
  • recognize basic Git concepts such as commits and repositories — you will not run Git locally.
  • edit plain-text files.

You don’t need any prior experience with software packaging, metadata standards, or licensing.

The optional final episode on reproducible environments with pixi is the only part that requires software installed on your computer. See Setup for both tracks.

Callout

Acknowledgment

This lesson is derived from the Building Better Research Software curriculum, created by Sarah Gibson, Aman Goel, Toby Hodges, Sarah Jaffa, Kamilla Kopec-Harding, Aleksandra Nenadic, Colin Sauze, and Sarah Stevens.

A full citation and DOI for the original lesson appear on this lesson’s Cite This Lesson page, automatically generated from the repository’s CITATION.cff file.

The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor.

This lesson runs almost entirely in your web browser. For most of it you need nothing more than a GitHub account. Only the optional final episode (reproducible environments with pixi) asks you to install software on your own computer.

Check with your instructor which track your workshop is running before you install anything.

  • Citation-focused track (default): licensing, CITATION.cff, releases, DOIs, and metadata. Browser only.
  • Full track: everything above, plus the optional pixi episode, which needs a local install.

Citation-focused track — browser only

You will fork a demo repository and add a license, a citation file, a release with a DOI, and metadata, all through GitHub’s web interface.

You need:

That is all: no Git, no terminal, and no other software are required for this track. A desktop text editor (VS Code, VS Codium, Sublime, …) is optional; GitHub’s built-in editor handles everything.

Fork the demo repository (do this before the workshop)

The lesson uses a demo repository called software-demo, and you work in your own fork of it.

  1. Sign in to GitHub.
  2. Go to https://github.com/UC-OSPO-Network/software-demo.
  3. Click Fork, then Create fork. The default settings are fine; you only need the main branch.
  4. You now have your own copy at https://github.com/YOUR-USERNAME/software-demo. Its main branch is the bare starting state — no license, citation file, release, or metadata. That is intentional; you will build it up over the lesson.
GitHub Create a new fork page for software-demo, with the 'Copy the main branch only' checkbox and the green 'Create fork' button highlighted.
On GitHub’s “Create a new fork” page, keep Copy the main branch only checked and click Create fork.
Callout

Checking your work: reference branches

The upstream repository (UC-OSPO-Network/software-demo) keeps view-only reference branches that show the target state after each episode:

Branch Shows the repo after…
main the starting state (what you fork)
after-license Episode 2, license added
after-citation Episode 3, CITATION.cff added
after-release Episode 4, release + DOI
after-metadata Episode 5, full metadata (the finished repo)
optional-pixi the optional pixi episode

If you fall behind or want to compare, open the upstream repo, switch to the matching branch in the branch dropdown, and look at the files. Because each episode adds an independent piece, falling behind never blocks you: you can copy a file you missed from its reference branch. You never edit the reference branches; they are an answer key.

Before the workshop, confirm

  • You can sign in to GitHub in your browser.
  • You have forked software-demo and can see it under your account.

If both are true, you are ready for the citation-focused track. There is nothing to install.

Full track only — local setup for the optional pixi episode

Caution

Set this up only if your instructor has confirmed the full track. The pixi episode is the one part of the lesson that runs on your own machine. If you are on the citation-focused track, skip this whole section — you do not need Git, a terminal, or pixi.

In addition to the GitHub account above, you will need Git, pixi, and a local clone of your fork.

1. Install Git

2. Install pixi

pixi is a fast, cross-platform environment and package manager.

Full instructions and troubleshooting: https://pixi.sh/latest/

3. Clone your fork

BASH 

git clone https://github.com/YOUR-USERNAME/software-demo.git
cd software-demo

Before the workshop, confirm (full track only)

Open a terminal and check that both tools respond:

BASH 

git --version
pixi --version
Callout

Authentication note

If you are prompted to authenticate when you clone, GitHub can sign you in through the browser: follow the link that appears in the terminal, sign in, and return. You do not need SSH keys or personal access tokens for this lesson.

Timing. Budget 5–10 minutes at the start to confirm everyone has a GitHub account and a fork of software-demo — this is the single most common blocker, so clear it before Episode 1. Full-track learners must install pixi ahead of the workshop, not mid-episode.

Verification. Ask learners to open their fork, click Add file → Create new file, and confirm they can commit to their main branch. For full-track learners, confirm git --version and pixi --version return values locally.

Common issues.

  • Some institutional devices require browser sign-in for GitHub access.
  • Windows full-track users may need to set Git Bash as the terminal in VS Code.
  • If pixi is installed but “not found,” restart the terminal (or VS Code) so PATH updates apply.

See the Instructor Notes for the full fork-alignment setup, including how to teach from your own fork so you and the learners share the same starting state.