Tags, Semantic Versioning & GitHub Releases

In software delivery, code reaches specific milestone states that represent official production releases (e.g. v1.0.0 or v2.4.1). While branches are dynamic pointers that continuously move forward as new commits are added, Tags are permanent, static markers in Git history that point forever to an exact commit snapshot.

Combining Git tags with Semantic Versioning (SemVer) and GitHub Releases establishes a standardized, automated release management pipeline for libraries and enterprise applications.

┌─────────────────────────────────────────────────────────────┐
│                 Semantic Versioning (SemVer 2.0)            │
│                                                             │
│                       v 2 . 4 . 1                           │
│                         │   │   │                           │
│             ┌───────────┘   │   └────────────┐              │
│             ▼               ▼                ▼              │
│        MAJOR              MINOR            PATCH            │
│   Breaking API        New Backward-    Backward-Compat      │
│     Changes            Compatible        Bug Fixes          │
│                         Features                            │
└─────────────────────────────────────────────────────────────┘

1. Lightweight vs Annotated Tags

Git supports two types of tags:

• Lightweight Tags: A simple, unannotated pointer to a commit hash (like an immutable branch).
• Annotated Tags (Recommended): Stored as full objects in the Git database containing a tagger name, email, timestamp, GPG cryptographic signature, and release message.

# Create an Annotated Tag (Recommended for releases)
git tag -a v1.0.0 -m "Release version 1.0.0: Initial production launch"

# Create a Lightweight Tag
git tag v1.0.0-beta.1

# List all tags in alphabetical / version order
git tag -l "v1.*"

# Inspect tag metadata and commit snapshot
git show v1.0.0

2. Publishing Tags to Remote Repositories

By default, git push does NOT transmit tags to remote servers. You must push tags explicitly:

# Push a specific tag to remote
git push origin v1.0.0

# Push ALL local tags to remote in a single command
git push origin --tags

# Delete a tag locally
git tag -d v1.0.0

# Delete a tag on the remote GitHub repository
git push origin --delete v1.0.0

3. GitHub Releases & Automated Changelogs

A GitHub Release enriches a Git tag with release notes, changelogs, and binary distribution assets (.zip, .deb, .apk, .js bundles).

On GitHub:

1. Navigate to Releases -> Draft a new release.
2. Select your pushed tag (e.g. v1.0.0).
3. Click Generate release notes: GitHub automatically scans all merged Pull Requests since the previous tag, categorizes them, and credits contributors.
4. Publish release!

Summary & Key Takeaways

• Tags are immutable milestone pointers in Git history.
• Always use Annotated Tags (git tag -a) for production releases to preserve tagger metadata.
• Semantic Versioning (MAJOR.MINOR.PATCH) communicates API compatibility to consumers.
• git push origin --tags publishes tags to remote servers.
• GitHub Releases link tags to automated changelogs and compiled deployment artifacts.

Best Practices & Senior Guidance

1. Follow SemVer Strictly: Never introduce breaking changes in a MINOR or PATCH version bump.
2. Prefix Tags with v: Use v1.0.0 rather than 1.0.0 to adhere to standard GitHub and npm tooling conventions.