Semantic Versioning Explained: MAJOR, MINOR, PATCH and Why It Matters in CI/CD

# This file illustrates which version number to bump
# in common real-world scenarios.

# Imagine your library is currently at version 2.4.5
current_version: "2.4.5"

scenarios:

  # SCENARIO 1: You found a null-pointer bug in the login module and fixed it.
  # Nothing was added or removed. Behavior is identical except the bug is gone.
  # ACTION: Bump the PATCH number. Reset nothing else.
  bug_fix:
    change_description: "Fixed null pointer exception in AuthService.validateToken()"
    old_version: "2.4.5"
    new_version: "2.4.6"   # PATCH went 5 -> 6. MAJOR and MINOR stay the same.
    is_breaking_change: false
    added_new_feature: false

  # SCENARIO 2: You added a new optional method getUserProfile() to the UserService.
  # Existing code that doesn't call getUserProfile() is completely unaffected.
  # ACTION: Bump the MINOR number. Reset PATCH to 0 (fresh slate for this feature).
  new_feature:
    change_description: "Added UserService.getUserProfile() method"
    old_version: "2.4.5"
    new_version: "2.5.0"   # MINOR went 4 -> 5. PATCH resets to 0.
    is_breaking_change: false
    added_new_feature: true

  # SCENARIO 3: You renamed the core authenticate() method to login() AND
  # changed the return type. Any code calling authenticate() will now crash.
  # ACTION: Bump the MAJOR number. Reset MINOR and PATCH to 0.
  breaking_change:
    change_description: "Renamed authenticate() to login(), changed return type from bool to AuthToken"
    old_version: "2.4.5"
    new_version: "3.0.0"   # MAJOR went 2 -> 3. MINOR and PATCH both reset to 0.
    is_breaking_change: true
    added_new_feature: false

# THE RESET RULE (critical to remember):
# When you bump MAJOR -> reset MINOR and PATCH to 0
# When you bump MINOR -> reset PATCH to 0, leave MAJOR alone
# When you bump PATCH -> leave MAJOR and MINOR alone

#!/bin/bash
# This script demonstrates how semantic versions are ordered
# and how to check them in a CI/CD shell script.

# --- PART 1: Understanding version precedence ---
# Versions ordered from OLDEST to NEWEST (left to right):
#
# 1.0.0-alpha.1
# 1.0.0-alpha.2
# 1.0.0-beta.1
# 1.0.0-rc.1
# 1.0.0          <-- official release
# 1.0.1
# 1.1.0
# 2.0.0

echo "=== Version Ordering Demo ==="
echo "Pre-release tags come BEFORE the official release:"
echo "  1.0.0-alpha.1  <  1.0.0-beta.1  <  1.0.0-rc.1  <  1.0.0"
echo ""

# --- PART 2: A simple bash function to check if a version is a pre-release ---
# In CI/CD you often need to block pre-release versions from auto-deploying.

is_prerelease_version() {
    local version_string="$1"  # e.g. "1.0.0-beta.2" or "2.3.1"

    # If the version string contains a hyphen, it's a pre-release.
    # We use bash's built-in string matching for this check.
    if [[ "$version_string" == *"-"* ]]; then
        echo "BLOCKED: '$version_string' is a pre-release — not safe for production auto-deploy."
        return 1  # non-zero exit code signals 'yes, it is a pre-release'
    else
        echo "APPROVED: '$version_string' is a stable release — safe to proceed."
        return 0  # zero exit code signals 'not a pre-release'
    fi
}

# --- Testing the function with different version strings ---
is_prerelease_version "2.3.1"          # Stable release
is_prerelease_version "1.0.0-alpha.1"  # Alpha — block it
is_prerelease_version "3.0.0-rc.2"    # Release candidate — block it
is_prerelease_version "1.5.0"          # Stable minor release

# A GitHub Actions CI/CD workflow that:
# 1. Runs on every push to main
# 2. Reads the new version from package.json
# 3. Decides the deployment strategy based on the version bump type
# 4. Blocks pre-release versions from reaching production

name: SemVer-Aware Deployment Pipeline

on:
  push:
    branches:
      - main  # Only triggers when code is merged to the main branch

jobs:
  determine_deployment_strategy:
    name: Analyse Version and Choose Deploy Path
    runs-on: ubuntu-latest

    steps:
      - name: Check out the repository code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Fetch full git history so we can compare tags

      - name: Read the current version from package.json
        id: read_version
        run: |
          # Extract the version field from package.json using jq (JSON parser)
          CURRENT_VERSION=$(jq -r '.version' package.json)
          echo "Current version: $CURRENT_VERSION"

          # Store the version so later steps can use it
          echo "current_version=$CURRENT_VERSION" >> $GITHUB_OUTPUT

      - name: Block pre-release versions from production
        run: |
          VERSION="${{ steps.read_version.outputs.current_version }}"

          # If the version contains a hyphen, it's a pre-release (e.g. 1.0.0-beta.1)
          if [[ "$VERSION" == *"-"* ]]; then
            echo "ERROR: Pre-release version '$VERSION' cannot be deployed to production."
            echo "Merge a stable release first."
            exit 1  # Fail the pipeline — this blocks the deployment entirely
          fi

          echo "Version '$VERSION' is stable. Proceeding with deployment."

      - name: Extract the MAJOR version number
        id: parse_version
        run: |
          VERSION="${{ steps.read_version.outputs.current_version }}"

          # Split on dots and grab the first segment (MAJOR number)
          MAJOR_VERSION=$(echo "$VERSION" | cut -d'.' -f1)
          echo "Major version: $MAJOR_VERSION"
          echo "major_version=$MAJOR_VERSION" >> $GITHUB_OUTPUT

      - name: Deploy PATCH or MINOR — straight to production
        # This step only runs if the major version hasn't changed from the last release
        # In a real pipeline you'd compare against the previous git tag
        run: |
          echo "Non-breaking change detected."
          echo "Running automated tests, then deploying directly to production..."
          # In a real workflow: ./scripts/deploy-to-production.sh

      - name: Notify team of successful deployment
        run: |
          VERSION="${{ steps.read_version.outputs.current_version }}"
          echo "Deployment complete. Released version $VERSION to production."
          # In a real workflow: post to Slack, PagerDuty, etc.

#!/bin/bash
# Conventional Commits format: <type>(<optional scope>): <short description>
#
# Tools like semantic-release scan these commit messages and
# automatically determine which version number to bump.
#
# FORMAT RULES:
# fix:   -> bumps PATCH  (2.4.5 -> 2.4.6)
# feat:  -> bumps MINOR  (2.4.5 -> 2.5.0)
# feat!: or a BREAKING CHANGE footer -> bumps MAJOR (2.4.5 -> 3.0.0)

echo "=== CORRECT Conventional Commit examples ==="
echo ""

# PATCH bump: a bug fix
git commit -m "fix(auth): resolve null pointer in token validation"
# Result: 2.4.5 -> 2.4.6

# PATCH bump: a documentation-only change (no version bump at all)
git commit -m "docs(readme): update installation instructions"
# Result: no version change

# MINOR bump: a new backwards-compatible feature
git commit -m "feat(users): add getUserProfile endpoint to UserService"
# Result: 2.4.5 -> 2.5.0

# MAJOR bump: exclamation mark after the type signals a breaking change
git commit -m "feat!(auth): rename authenticate() to login(), return AuthToken instead of bool"
# Result: 2.4.5 -> 3.0.0

# MAJOR bump alternative: use a BREAKING CHANGE footer in a multi-line commit
git commit -m "feat(auth): redesign authentication flow

BREAKING CHANGE: The authenticate() method has been removed.
Callers must migrate to login() which returns an AuthToken object."
# Result: 2.4.5 -> 3.0.0

echo "=== WRONG commits that would cause version confusion ==="

# WRONG: Using 'fix' for something that actually adds a feature
git commit -m "fix(users): add admin role support"  # Should be feat!

# WRONG: Using 'feat' for a breaking rename
git commit -m "feat(auth): rename authenticate to login"  # Should be feat! (MAJOR)

echo "Tip: if you're unsure between fix and feat, ask:"
echo "'Did I add something new?' -> feat"
echo "'Did I only repair existing behaviour?' -> fix"