Archiving & Publishing

Let’s think about the future…

  • Will this repository still be here in five years?
  • Will my account still be here?
  • Will GitHub still exist in its current form?

Why Archiving Matters

  • GitHub is not a long‑term archive.
  • Repositories can be deleted, accounts can disappear, platforms can change.
  • For reproducible research, we need:
    • stability (a version that won’t change)
    • citeability (a DOI)
    • findability (persistent identifier)
    • reproducibility (retrieve the exact version used)

To achieve this, we distinguish between:

  • a software release (GitHub)
  • a software publication (Zenodo)

What Is a Software Release?

A software release is a snapshot of your repository at a specific moment in time.

Characteristics

  • Stable, tested version
  • Has a version number
  • Includes release notes
  • Downloadable as .zip or .tar.gz
  • May evolve, future releases can follow

When to create a release

  • Reaching a reliable milestone
  • Preparing a workshop or teaching
  • Fixing major bugs or adding features
  • Freezing a version before refactoring

A release is not a long‑term archive.

A Word on Version Numbers

  • A version number communicates the state, stability, and evolution of your software.

  • Two common conventions

Semantic Versioning (SemVer)

MAJOR.MINOR.PATCH
  • MAJOR — breaking changes
  • MINOR — new features, compatible
  • PATCH — bug fixes

Use when you want to signal how safe it is for others to upgrade.

Calendar Versioning (CalVer)

YY.MM.MICRO
  • Based on release date
  • Emphasises freshness

Use for fast‑moving research code or teaching materials.

What Is a Software Publication?

A software publication is a permanent, citable archived copy of a release.

Characteristics

  • Frozen, immutable version
  • Stored in a long‑term archive (Zenodo)
  • Assigned a DOI
  • Includes citation metadata (CITATION.cff)
  • Guaranteed long‑term accessibility

When to archive a release

  • Publishing a paper or report
  • Project is finished or inactive
  • Reproducibility is required
  • A journal or funder requires a DOI

Workflow Overview

%%{init: {
  "theme": "forest",
  "look": "handDrawn",
  "flowchart": { "htmlLabels": false }
}}%%
flowchart LR
    A[Prepare repo] --> B[Enable integration]
    B --> C[Create release]
    C --> D[Zenodo detects]
    D --> E[Review record]
    E --> F[Cite software]

Prepare repo: README, LICENSE, CITATION.cff
Enable integration: Log in to Zenodo · Authorize GitHub · Toggle repo ON
Create release: Choose version number · Add notes · Publish
Zenodo detects: Creates record · Assigns DOI
Review record: Check metadata · Publish archive
Cite software: Use DOI · CITATION.cff provides citation text

Exercise (optional)

Follow the workflow outlined in this guide to archive your code to Zenodo. Use the Sandbox version of Zenodo to make sure your repository is not actually archived permanently!

Are you ready?

Exchange projects!
Share your GitHub repository with a neighbour.

Try to reproduce each other’s project.

Open an issue in their repository using the
feedback template