Tags & Releases — Version Management

Module 05 45 min

---

Section Objectives

• Create and manage annotated and lightweight tags
• Apply semantic versioning (SemVer)
• Create GitHub releases with release notes
• Automate releases with GitHub Actions

---

What is a Tag?

A tag is a permanent reference to a specific commit. Unlike a branch that moves with new commits, a tag stays fixed.

---

Semantic Versioning (SemVer)

SemVer format: MAJOR.MINOR.PATCH

v2.1.3
│ │ └── PATCH: Bug fix, backward compatible
│ └──── MINOR: New feature, backward compatible
└────── MAJOR: Breaking change, incompatible API

Version	When to Increment	Example
MAJOR	Breaking API change	v1.0 → v2.0
MINOR	New feature, backward compatible	v1.0 → v1.1
PATCH	Bug fix	v1.0.0 → v1.0.1

# Special versions
v1.0.0-alpha.1     # Alpha (unstable, internal)
v1.0.0-beta.2      # Beta (feature complete, testing)
v1.0.0-rc.1        # Release Candidate (near final)
v1.0.0             # Stable release

---

Creating Tags

Lightweight Tags

Simple pointer to a commit, no metadata:

# Create a lightweight tag
git tag v1.0.0

# Tag a specific commit
git tag v0.9.0 abc1234

# List tags
git tag
git tag -l "v1.*"   # Filter by pattern

Annotated Tags (Recommended)

Contain metadata: author, date, message, GPG signature:

# Create an annotated tag
git tag -a v1.0.0 -m "Version 1.0.0 - First stable release"

# Tag a specific commit
git tag -a v1.0.0 abc1234 -m "Version 1.0.0"

# View tag details
git show v1.0.0

# List with message
git tag -n         # Show first line of each tag message
git tag -n5        # Show first 5 lines

Pushing Tags to GitHub

# Push a specific tag
git push origin v1.0.0

# Push all tags
git push --tags

# Push and create a GitHub release
gh release create v1.0.0

Deleting Tags

# Delete local tag
git tag -d v1.0.0

# Delete remote tag
git push origin --delete v1.0.0
git push origin :refs/tags/v1.0.0   # Equivalent

# Recreate a tag (if you tagged the wrong commit)
git tag -d v1.0.0
git tag -a v1.0.0 correct-commit-hash -m "Version 1.0.0"
git push origin --delete v1.0.0
git push origin v1.0.0

---

GitHub Releases

GitHub Releases wrap a tag with release notes, binaries, and detailed documentation.

Create a Release via CLI

# Simple release
gh release create v1.0.0 --title "v1.0.0 - First Stable Release"

# Release with generated notes (from merged PRs since last release)
gh release create v1.0.0 --generate-notes

# Release with custom notes
gh release create v1.0.0 \
  --title "v1.0.0 - First Stable Release" \
  --notes "## What's New

### New Features
- User authentication with JWT
- Task management dashboard
- Advanced search with filters
- Real-time statistics

### Bug Fixes
- Fixed division by zero in statistics
- Corrected email validation regex
- Fixed mobile cart button

### Breaking Changes
None in this release.

### Migration
No migration needed from v0.x.

## Downloads
The application is available as a Docker image:
\`\`\`bash
docker pull myapp:1.0.0
\`\`\`"

# Release from a specific tag with attachments (binaries)
gh release create v1.0.0 \
  --title "v1.0.0" \
  --notes-file RELEASE_NOTES.md \
  dist/myapp-linux-amd64 \
  dist/myapp-windows.exe \
  dist/myapp-macos

# Pre-release (beta, alpha)
gh release create v1.1.0-beta.1 --prerelease --title "v1.1.0 Beta 1"

# Draft release (not published yet)
gh release create v1.1.0 --draft --title "v1.1.0 (Draft)"

Create a Release via GitHub UI

1. Go to your repository → Releases → Create a new release
2. Click Choose a tag → Create new tag (e.g., v1.0.0)
3. Target: main (or the release branch)
4. Title: v1.0.0 - First Stable Release
5. Description: Detailed release notes
6. Attach binaries if needed
7. Choose: Stable release / Pre-release / Draft
8. Click Publish release

---

Automating Releases with GitHub Actions

# .github/workflows/release.yml
name: Create Release

on:
  push:
    tags:
      - 'v*'   # Triggers on every tag starting with 'v'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          generate_release_notes: true
          draft: false
          prerelease: ${{ contains(github.ref, 'alpha') || contains(github.ref, 'beta') || contains(github.ref, 'rc') }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

---

CHANGELOG Management

# CHANGELOG.md
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- Dark mode support

## [1.0.0] - 2026-03-18

### Added
- User authentication with JWT
- Task management with priorities
- Statistics dashboard
- Advanced search

### Fixed
- Division by zero in statistics function

## [0.9.0] - 2026-02-01

### Added
- Basic task creation and listing
- Priority levels

[Unreleased]: https://github.com/user/repo/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/user/repo/compare/v0.9.0...v1.0.0
[0.9.0]: https://github.com/user/repo/releases/tag/v0.9.0

---

Summary

Command	Description
git tag -a v1.0.0 -m "msg"	Create annotated tag
git tag -l "v1.*"	List matching tags
git show v1.0.0	View tag details
git push --tags	Push all tags
git tag -d v1.0.0	Delete local tag
gh release create v1.0.0	Create GitHub release
gh release list	List all releases

---

Next Steps

• git cherry-pick & git bisect
• Git Hooks