Archiving & Publishing: Releases vs. Software Publications

Overview

Questions Objectives Concepts
Why distinguish between a release and a publication? Understand the roles of GitHub releases vs. Zenodo archives Software release, Software publication
How do I create a stable version of my software? Learn how and when to make a release on GitHub Version numbers, SemVer, CalVer
How does my code become citable? Provide citation metadata and archive a release CITATION.cff, DOI for software
How do I archive my software? Enable GitHub - Zenodo integration and publish a permanent record Zenodo integration, Software archiving

Why This Matters

In reproducible research, it is not enough to share your code. You must also make it:

  • stable (a version that won’t change)
  • citable (with a DOI)
  • findable (in a long‑term archive)
  • reproducible (others can retrieve the exact version you used)

To achieve this, we distinguish between:

  • a software release (created on GitHub)
  • a software publication (archived on Zenodo)

These two concepts are related but serve different purposes.

What Is a Software Release?

A software release is a snapshot of your repository at a specific moment in time.
It is created on GitHub and is intended for users, collaborators, and developers.

Characteristics of a Release

  • Represents a stable, tested version of your software
  • Uses a version number
  • Includes release notes describing changes
  • Can be downloaded as a .zip or .tar.gz
  • May still evolve, future releases can follow

When to Create a Release

A release is appropriate when:

  • Your software reaches a reliable milestone
  • You want to communicate a stable version to users
  • You fix major bugs or add significant features
  • You prepare for a publication or workshop
  • You want to freeze a version before major refactoring

Why Releases Matter

Releases help users know:

  • which version is stable
  • which version they should cite
  • which version matches your documentation
  • which version is used in a paper or analysis

A release is not a long‑term archive.
It is a versioned snapshot, but GitHub does not guarantee long‑term preservation.

A word on Version Numbers

A version number communicates the state, stability, and evolution of your software. It helps users know which version to install, and it supports reproducibility when linking code to publications.

Two Common Conventions

  1. Semantic Versioning (SemVer) Structure:
    MAJOR.MINOR.PATCH

    • MAJOR — breaking changes
    • MINOR — new features, backwards‑compatible
    • PATCH — bug fixes only

    Use SemVer when you want to communicate how safe it is for others to upgrade and when your software is used by others in a stable, predictable way.

  2. Calendar Versioning (CalVer) Structure (common form):
    YY.MM.MICRO

    • Based on the release date
    • Communicates freshness rather than compatibility

    Use CalVer when your project follows time‑based releases or evolves quickly (e.g., research code, teaching materials).

When to Use Which

Situation Recommended
Stable library, public API SemVer
Fast‑moving research code CalVer
Teaching templates CalVer
Long‑term maintained package SemVer

What Is a Software Publication (Zenodo Archive)?

A software publication is a permanent, citable archived copy of a release.
It is stored in a long‑term repository such as Zenodo, which issues a DOI.

Characteristics of a Software Publication

  • A frozen, immutable copy of a specific release
  • Stored in a long‑term archive (Zenodo)
  • Assigned a persistent identifier (DOI)
  • Includes citation metadata (from CITATION.cff)
  • Guaranteed to remain accessible for decades

When to Archive a Release

Archiving is appropriate when:

  • You publish a paper, report, or dataset
  • You need a citable version of your software
  • Your project is finished or becomes inactive
  • You want to ensure long‑term preservation
  • A journal or funder requires a DOI
  • You want to support reproducibility:
    others must retrieve the exact version you used

Why Archiving Matters

Archiving ensures:

  • Permanence: the version will not disappear
  • Citeability: DOIs are standard in scholarly communication
  • Reproducibility: others can retrieve the exact version
  • Compliance: many journals require archived software

How Releases and Publications Work Together

A release and a publication are two steps in one workflow:

  1. Create a release on GitHub
    → defines a stable version of your software

  2. Archive that release on Zenodo
    → makes it permanent and citable

This workflow ensures that:

  • GitHub handles development, versioning, collaboration
  • Zenodo handles preservation, metadata, DOIs

They complement each other.

Workflow Summary

To practice follow the steps of the GitHub Documentation.

1. Prepare Your Repository

  • Ensure your repository contains:
    • a clear README
    • a LICENSE
    • a CITATION.cff file with correct metadata
  • Commit and push all changes before creating a release.

2. Enable GitHub - Zenodo Integration

  • Log in to Zenodo (or the Zenodo Sandbox for testing).
  • Authorize Zenodo to access your GitHub account.
  • Go to your GitHub → Zenodo settings page.
  • Locate your repository and toggle it on.
  • Zenodo will now monitor this repository for new releases.

3. Create a Release on GitHub

  • Navigate to Releases in your repository.
  • Click Draft a new release.
  • Choose a version number (SemVer or CalVer).
  • Add a tag, title and release notes.
  • Publish the release.

Zenodo only archives published releases, not tags alone.

4. Zenodo Detects the Release

  • After publishing, Zenodo automatically:
    • retrieves the release
    • creates a new record
    • assigns a DOI
  • This may take a few minutes.

5. Review and Finalize the Zenodo Record

  • Open the Zenodo record linked from your release.
  • Check:
    • title
    • authors
    • version
    • license
    • description
    • related identifiers (e.g., GitHub URL)
  • Correct any metadata issues.
  • Publish the record.

Once published, the archived version becomes immutable.

6. Cite the Software

  • Use the DOI provided by Zenodo.
  • GitHub and Zenodo both read your CITATION.cff file to generate citation text.
  • Include the DOI in:
    • papers
    • reports
    • datasets
    • documentation

When to Use What

Situation Use a Release Use a Zenodo Publication
You want to mark a stable version ✔️
You want users to download a tested version ✔️
You are preparing a workshop or teaching ✔️
You are submitting a paper ✔️
You need a DOI ✔️
You want long‑term preservation ✔️
Your project is finished or inactive ✔️
You want reproducibility for others ✔️ ✔️

Rule of thumb: - A release is for users.
- A Zenodo publication is for scholarly citation and preservation.

Slides

Exercise (optional)