Skip to content

Chapter 10 — Releases

Overview

A GitHub Release packages a specific state of the code with release notes, a version tag, and optional binary assets. For a research group, releases mark scientifically significant milestones: paper submissions, conference presentations, and stable versions shared with collaborators.

What Is a Release?

A GitHub Release consists of:

  • A Git tag (the specific commit being released)
  • A title (human-readable version name)
  • Release notes (what changed)
  • Optional binary assets (compiled executables, data files)
  • A source code archive (zip and tar.gz automatically generated by GitHub)

When to Create a Release

Event Create a release?
Paper submitted to journal ✓ Yes — tag the exact code state
Paper posted to arXiv ✓ Yes
Conference presentation ✓ Yes — reproducibility of presented results
Stable version for collaborators ✓ Yes
Mid-development checkpoint ✗ No — use a tag only (Chapter 11)
Every merged PR ✗ No — too granular

Semantic Versioning

All releases use Semantic Versioning: MAJOR.MINOR.PATCH

Component When to increment Example
MAJOR Incompatible API or physics changes 1.0.0 → 2.0.0
MINOR New features, backward compatible 1.0.0 → 1.1.0
PATCH Bug fixes, no new features 1.0.0 → 1.0.1

For research code:

  • The first stable, tested version is v1.0.0
  • New calculations added → increment MINOR
  • Bug fixes → increment PATCH
  • Major restructuring or incompatible parameter changes → increment MAJOR

Pre-release versions (before v1.0.0): use v0.x.y

Release Timeline

Releases and tags mark significant moments in the development history:

gitGraph
   commit id: "Initial"
   commit id: "Feature A"
   commit id: "Feature B" tag: "v0.1.0"
   commit id: "Feature C"
   commit id: "Bug fix" tag: "v0.1.1"
   commit id: "Feature D"
   commit id: "Refactor" tag: "v1.0.0 (paper submission)"

Pre-Release Checklist

Before creating a release, verify:

  • All intended PRs are merged into main
  • Tests pass on main
  • Documentation is up to date
  • CHANGELOG or release notes are prepared
  • No temporary branches or debug code on main
  • README reflects the current state accurately
  • PI has reviewed (for paper-submission releases)

Creating a Release via GitHub UI

  1. Navigate to Releases → Draft a new release
  2. Click "Choose a tag" → type a new tag name (e.g., v1.2.0) → click "Create new tag on publish"
  3. Set Target: main (always release from main)
  4. Release title: v1.2.0 or v1.2.0 — Paper submission to PRD
  5. Description: write release notes (see format below)
  6. Check "Set as the latest release" unless this is a pre-release
  7. Click "Publish release"

GitHub will create the annotated tag and the source code archives automatically.

Writing Release Notes

Good release notes help future users (including yourself) understand what changed and why. Organise by category:

## v1.2.0 — 2026-07-10

This release corresponds to the code submitted with arXiv:XXXX.XXXXX.

### New Features

- Added one-loop thermal correction to effective potential (#42)
- Added gravitational wave spectrum calculator (#51)

### Bug Fixes

- Fixed interpolation overflow at high temperature (#55)
- Corrected sign error in bubble nucleation rate (#57)

### Documentation

- Updated installation instructions for macOS (#61)
- Added worked example in docs/examples/ (#63)

### Breaking Changes

- `compute_potential()` now requires `include_thermal` keyword argument.
  Update existing code: `compute_potential(phi, T, include_thermal=False)`

Attaching Assets

For most research code releases, the auto-generated source archive is sufficient. Attach additional assets only when:

  • Pre-compiled binaries are provided for reproducibility
  • Large input data files are needed to run the code
  • A specific dataset snapshot is being archived with the release

Attach via drag-and-drop in the release creation form, or the GitHub CLI:

gh release upload v1.2.0 data/input-parameters.hdf5

Common Mistakes

  1. Creating a release from a branch instead of main. Always release from main. The tag points to main's HEAD at release time.

  2. Empty or vague release notes. Future you (or a reviewer) will need to know what version was used for a figure. Describe what is new and what is fixed.

  3. Forgetting to push the tag. When creating a release via the GitHub UI, the tag is created automatically. When creating a tag locally and pushing, remember git push origin v1.2.0.

  4. Using pre-release for all releases. Mark pre-release only if the release is genuinely experimental or incomplete.

Checklist

  • Pre-release checklist completed
  • Tag follows semantic versioning (e.g., v1.2.0)
  • Release created from main
  • Release notes written (new features, bug fixes, breaking changes)
  • Paper arXiv ID referenced in release notes if applicable
  • Release set as "latest" (unless pre-release)