Releases and Release Notes

The Hook (The "Byte-Sized" Intro)

A tag says "this is version 1.0." A release says "this is version 1.0, here's what changed, here's the download, and here's how to upgrade." Tags are for machines. Releases are for humans. Every serious project turns tags into releases with notes that tell users what's new, what's fixed, and what broke.

📖 What is a Release?

A release is a published version of your software tied to a Git tag. Platforms like GitHub and GitLab provide a releases feature that bundles the tag with release notes, binary assets, and changelogs.

Conceptual Clarity

Release anatomy:

Component	Purpose
Tag	Points to the exact commit (immutable reference)
Title	Version name (e.g., "v1.2.0 - Dark Mode")
Release notes	What's new, fixed, or breaking
Assets	Download links (binaries, packages, archives)
Pre-release flag	Marks alpha/beta/RC versions

Good release notes structure:

markdown

## What's New
- Added dark mode (#123)
- Added CSV export (#145)

## Bug Fixes
- Fixed login redirect loop (#167)
- Fixed timezone display issue (#172)

## Breaking Changes
- Removed deprecated `/api/v1` endpoints

## Upgrade Guide
- Update config file: `theme: auto`

Real-Life Analogy

A tag is like a version number stamped on a product. A release is the full product announcement: the version number plus "what's new," user guides, and download links — everything a customer needs.

Visual Architecture

flowchart LR TAG["🏷️ Tag v1.2.0"] --> RELEASE["📦 Release"] RELEASE --> NOTES["📝 Release Notes"] RELEASE --> ASSETS["📁 Download Assets"] RELEASE --> PRE["⚠️ Pre-release Flag"] style TAG fill:#1a1a2e,stroke:#ffd700,color:#ffd700 style RELEASE fill:#0f3460,stroke:#53d8fb,color:#53d8fb

Why It Matters

User communication: Release notes tell users whether to upgrade.
Download distribution: Attach binaries so users don't need to build from source.
Change tracking: Notes create a historical record of every version's changes.
GitHub integration: GitHub auto-generates changelogs from PRs.

Code

bash

# ─── Create a tag first ───
git tag -a v1.2.0 -m "Release: Dark Mode support"
git push origin v1.2.0

# ─── Create a GitHub release (CLI) ───
gh release create v1.2.0 \
  --title "v1.2.0 - Dark Mode" \
  --notes "## What's New\n- Added dark mode\n- Added CSV export" \
  ./build/app.zip

# ─── Auto-generate release notes from PRs ───
gh release create v1.2.0 --generate-notes
# GitHub automatically lists merged PRs since last release

# ─── Create a pre-release ───
gh release create v2.0.0-beta.1 --prerelease \
  --title "v2.0.0 Beta 1" \
  --notes "Early preview of API v2"

# ─── List releases ───
gh release list

# ─── Download a release asset ───
gh release download v1.2.0

Key Takeaways

A release = tag + release notes + optional download assets.
Write release notes with clear sections: New, Fixes, Breaking, Upgrade Guide.
Use gh release create --generate-notes for auto-generated changelogs.
Mark unstable versions as pre-releases.

Interview Prep

Q: What is the difference between a tag and a release? A: A tag is a Git object pointing to a specific commit. A release is a platform feature (GitHub/GitLab) built on top of a tag that adds release notes, binary assets, and metadata. Tags are version control; releases are distribution.
Q: How do you auto-generate release notes on GitHub? A: Use gh release create <tag> --generate-notes. GitHub generates notes from merged PRs since the last release, grouping them by labels. You can customize the format with a .github/release.yml configuration file.
Q: What should release notes include? A: At minimum: new features, bug fixes, and breaking changes. Ideally also: an upgrade guide, contributor acknowledgments, and links to relevant issues/PRs. Users read release notes to decide whether to upgrade.