Publishing, packaging, releasing and archiving software
Use this skill when helping someone move research software from a working
repository to something others can find, install, run, cite, and rely on
years from now. These are four distinct stages that people routinely
conflate; get the vocabulary straight first, then follow the stage the
user actually needs.
Distinguish the four stages
Keep these separate when advising - they answer different questions:
- Publishing - making software available so others can find, use, and cite
it. Putting code on GitHub/GitLab is the start, not the whole job.
- Packaging - preparing the software so others can install and run it with
a single command or download (structure, config files, metadata).
- Releasing - packaging one specific stable version for people to download
and run, tagged with a version number.
- Archiving - long-term preservation independent of any one platform, so
the exact software survives even if a hosting service disappears.
Publishing is the umbrella; packaging, releasing, and archiving are the
concrete sub-tasks that make a publication findable, installable, and
durable.
Publishing: the end-to-end order
Publishing is more than pushing to a public repo. Walk these tasks in this
order, because each depends on the previous ones:
- Write release notes, a changelog, and usage instructions.
- Add metadata for discoverability, and capture dependencies and
environments (containers, environment files, or workflow systems) so
the release is reproducible.
- Choose and apply an appropriate open license (delegate to the licensing
skill for selection).
- Add citation files (CITATION.cff), contribution guidelines, and
community practices to support reuse and credit.
- Version and release a stable, installable build - as a package in a
registry, or by tagging an official release in the code repository.
- Archive the release (Zenodo or Software Heritage) with a DOI.
Treat this list as the checklist for "is this really published, or just
pushed?" Anything missing above is a gap to flag.
Packaging: choose the distribution channel
Pick the channel by how users need to consume the software:
- Just sharing source and history, or a first open release -> a code
hosting platform (GitHub, GitLab, BitBucket). This is the hub even when
users ultimately install from elsewhere; source and development history
live here, and releases can be tagged with notes and downloadable
archives.
- Users need to install and reuse the code from their own environment -> a
language or discipline package registry. Match the ecosystem: PyPI
(Python), CRAN (R), npm (JavaScript), conda-forge (multi-language),
Maven Central (Java). These give one-command installs, versioned
distribution, and metadata-driven discoverability.
- The software depends on many tools or a specific environment, or must
run identically everywhere -> ship a container (Docker, SingularityCE)
or publish a workflow to a hub (WorkflowHub, Dockstore). Containers
bundle the runtime so users pull and run with no manual setup.
Whichever channel, package with a standard project structure, package
config files (pyproject.toml, package.json, and equivalents), and
metadata: version number, authors, dependencies, and license. A single project often uses several channels at once
(source on GitHub, installable package on PyPI, container on a registry).
Releasing: version, changelog, tag
A release is a new or updated version made available to users; it is a
phase in the development cycle, not a one-off upload. Do these:
- Pick a versioning scheme and apply it consistently:
- Semantic Versioning (e.g. 1.0.2) - communicates compatibility:
MAJOR breaks the API, MINOR adds compatibly, PATCH fixes. Prefer this
for libraries others build against.
- Calendar Versioning (e.g. 24.10) - encodes the release date. Prefer
this for tools released on a schedule where date matters more than API
compatibility.
- Maintain a changelog (release log): a running record of changes,
published with the software at release time. Prepare it before starting
the release, not after.
- Write release notes: a short, non-technical summary of the changelog
aimed at end users, distinct from the raw changelog.
- Attach built artefacts (binaries, packages) to the release where useful.
Concrete GitHub release flow:
- Prepare the changelog ahead of time.
- In the repo, open
Releases -> Draft a new release.
- Assign a unique version name/number under your chosen scheme.
- Add end-user-facing release notes.
Publish release.- If the repo is connected to Zenodo, publishing the release
automatically mints a DOI for that version - enable this integration so
citation and archiving happen in one step.
Archiving: preserve beyond the platform
Code on GitHub or GitLab is good for sharing and versioning but is not
archiving: these are commercial services that can change policies, remove
repos, or shut down, and research outputs go irreproducible within a few
years when the original software vanishes.
Archiving means preservation that does not depend on any single platform.
Why it matters: reproducibility of past experiments, preservation of the
tools behind published results, compliance with Open Science mandates from
funders and journals, and continued citation and reuse.
Address more than the source code when archiving:
- Environment - capture compilers, libraries (NumPy, R packages),
OS-level features, and architectures the software needs.
- Build reproducibility - non-deterministic builds and missing historical
dependencies make byte-for-byte rebuilds hard; document the build.
- Versioning and provenance - record version history, commit hashes, and
links to specific datasets and publications.
- Legacy execution - for old software, plan for emulation or VM snapshots
when containers are not enough (GUI or legacy apps).
- Licensing - proprietary dependencies can legally limit what may be
archived and shared.
- Metadata and documentation - machine- and human-readable metadata,
usage instructions, authorship, and configuration must travel with the
archive.
Match the archival tool to the need:
- Zenodo (or an institutional repository) - DOI-backed archiving of a
release, linked to publications; the default for a citable snapshot.
- Software Heritage - universal archive of source code and its full
development history at scale.
- ReproZip - captures the execution environment for portability.
- Guix / NixOS - functional package managers for reproducible builds.
- Containers (Docker, SingularityCE) - bundle app plus dependencies,
common in HPC; VM snapshots when containerisation is not feasible.
- RO-Crate - not an archive itself but the metadata format that keeps
archived items (e.g. workflows) described, understandable, and reusable.
Rule of thumb: mint a DOI on Zenodo for the citable release, and register
the source with Software Heritage for the full history; add
environment-capture tools when exact re-execution is a requirement.
A concrete release stack (NLeSC python-template): setuptools-scm
derives versions from git tags, bump-my-version manages the bump, and
Zenodo integration mints a DOI wired to CITATION.cff on each GitHub
release.
Working with this skill
The generated references.md beside this file lists the source
material and pointers:
- references.md - verified Learn more pointers
Learn more (verified):
<!-- related-skills:begin -->
Related skills
Check whether any of these applies before moving on:
- rseng-archiving - preservation follows each release
- rseng-ci-cd - release automation pipelines
- rseng-citation-metadata - DOI and CITATION.cff at release
- rseng-legacy-code - retire path needs tagged archive
- rseng-license-compliance - notice obligations at release time
- rseng-software-publishing - channel craft after cutting release
<!-- related-skills:end -->