Key Points

Introduction: The "Works on My Machine" Trap

  • Research software often fails due to the “works on my machine” trap
  • The bus factor problem means knowledge is lost when people leave
  • Software citations using URLs break over time; DOIs are permanent and version-specific
  • FAIR4RS principles (Findable, Accessible, Interoperable, Reusable) provide a framework
  • Making software FAIR requires: LICENSE, environment files, citation metadata, and documentation
  • A CITATION.cff file is the simplest way to make software citable
  • The demo repository progresses through branches: 01-start → 06-metadata

Sharing Research Software Effectively

  • Public repositories increase findability, reuse potential, and citation credit.
  • A well-structured repository lowers the barrier for others to understand your work.
  • The lesson begins with a minimal “before” repository that will be incrementally improved.

Choosing an Open-Source License

  • Without a license, software is legally restricted and not reusable
  • BSD 3-Clause is a common default at research institutions; MIT and Apache 2.0 are strong alternatives
  • Permissive licenses (BSD, MIT, Apache 2.0) maximize flexibility and adoption
  • Always consult your institution’s Tech Transfer or IP office before releasing institutionally-owned software
  • GitHub makes adding standard licenses straightforward

Adding a CITATION.cff File

  • A CITATION.cff file is the foundation of software citation.
  • It can be added before releases, DOIs, or version tags.
  • GitHub displays machine-readable citations automatically when this file is present.
  • Start simple and expand over time as your project develops.

Making Your Software Citable

  • Software is citable as soon as it includes a citation file and a stable version.
  • GitHub releases create versioned snapshots for citation.
  • DOIs are optional but strengthen discoverability, persistence, and reproducibility.
  • Zenodo can automatically mint a DOI for each GitHub release.

Managing Reproducible Environments with pixi

  • Reproducible environments reduce troubleshooting and support more reusable software.
  • pixi provides fast, cross platform environment management.
  • The pixi.toml file acts as documentation that supports citation and FAIR4RS principles.
  • Use pixi run to execute Python or R code inside a reproducible environment.

Improving Metadata and Discoverability

  • Metadata increases discoverability in GitHub, Zenodo, and scholarly indexes.
  • Use consistent information across CITATION.cff, README, GitHub topics, and Zenodo.
  • Thoughtful metadata supports FAIR principles and helps others reuse your software.

Wrap-Up and Reflection

  • You’ve successfully made your software FAIR: Findable, Accessible, Interoperable, and Reusable
  • Even small actions can significantly improve your software’s impact
  • Making code citable and discoverable benefits both you and the research community
  • Start with one change, then build from there
  • Use the UC OSPO resources and templates to streamline the process