semantic-versioning

Implement semantic versioning (SemVer) with automated release management. Use conventional commits, semantic-release, and version bumping strategies.

⭐25stars🔀1forks📁View on GitHub🕐Updated Dec 28, 2025

When & Why to Use This Skill

This Claude skill automates the implementation of Semantic Versioning (SemVer) and release management workflows. By leveraging conventional commits and semantic-release strategies, it ensures consistent version numbering, automated changelog generation, and streamlined deployment processes, significantly reducing manual overhead and errors in the software release lifecycle.

Use Cases

  • Automating version bumps (Major, Minor, Patch) by analyzing standardized commit messages to determine the impact of changes.
  • Generating professional and comprehensive changelogs automatically for GitHub, NPM, or internal documentation to keep stakeholders informed.
  • Integrating automated release logic into CI/CD pipelines, such as GitHub Actions, to trigger deployments and tag releases upon code merges.
  • Managing breaking changes and API versioning consistency across complex software projects to ensure reliable dependency management.
namesemantic-versioning
descriptionImplement semantic versioning (SemVer) with automated release management. Use conventional commits, semantic-release, and version bumping strategies.

Semantic Versioning

Overview

Establish semantic versioning practices to maintain consistent version numbering aligned with release significance, enabling automated version management and release notes generation.

When to Use

  • Package and library releases
  • API versioning
  • Version bumping automation
  • Release note generation
  • Breaking change tracking
  • Dependency management
  • Changelog management

Implementation Examples

1. Semantic Versioning Configuration

# package.json
{
  "name": "my-awesome-package",
  "version": "1.2.3",
  "description": "An awesome package",
  "main": "dist/index.js",
  "repository": {
    "type": "git",
    "url": "https://github.com/org/repo.git"
  },
  "scripts": {
    "release": "semantic-release"
  },
  "devDependencies": {
    "semantic-release": "^21.0.0",
    "@semantic-release/changelog": "^6.0.0",
    "@semantic-release/git": "^10.0.0",
    "@semantic-release/github": "^9.0.0",
    "conventional-changelog-cli": "^3.0.0"
  }
}

2. Conventional Commits Format

# Feature commit (MINOR bump)
git commit -m "feat: add new search feature"
git commit -m "feat(api): add pagination support"

# Bug fix commit (PATCH bump)
git commit -m "fix: resolve null pointer exception"
git commit -m "fix(auth): fix login timeout issue"

# Breaking change (MAJOR bump)
git commit -m "feat!: redesign API endpoints"
git commit -m "feat(api)!: remove deprecated methods"

# Documentation
git commit -m "docs: update README"

# Performance improvement
git commit -m "perf: optimize database queries"

# Refactoring
git commit -m "refactor: simplify authentication logic"

# Tests
git commit -m "test: add integration tests"

# Chore
git commit -m "chore: update dependencies"

# Complete example with body and footer
git commit -m "feat(payment): add Stripe integration

Add support for processing credit card payments via Stripe.
Includes webhook handling for payment confirmations.

BREAKING CHANGE: Payment API endpoint changed from /pay to /api/v2/payments
Closes #123"

3. Semantic Release Configuration

// release.config.js
module.exports = {
  branches: ['main', {name: 'develop', prerelease: 'beta'}],
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    '@semantic-release/changelog',
    '@semantic-release/git',
    '@semantic-release/github',
    '@semantic-release/npm'
  ]
};

4. Version Bumping Script

#!/bin/bash
# bump-version.sh

CURRENT_VERSION=$(grep '"version"' package.json | head -1 | sed 's/.*"version": "\([^"]*\)".*/\1/')
IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"

case "${1:-patch}" in
  major)
    NEW_VERSION="$((MAJOR + 1)).0.0"
    ;;
  minor)
    NEW_VERSION="$MAJOR.$((MINOR + 1)).0"
    ;;
  patch)
    NEW_VERSION="$MAJOR.$MINOR.$((PATCH + 1))"
    ;;
  *)
    echo "Usage: $0 {major|minor|patch}"
    exit 1
    ;;
esac

echo "Bumping version from $CURRENT_VERSION to $NEW_VERSION"

# Update package.json
npm version $NEW_VERSION --no-git-tag-v

# Update CHANGELOG
CHANGELOG_HEADER="## [$NEW_VERSION] - $(date +%Y-%m-%d)"
sed -i "1i\\$CHANGELOG_HEADER" CHANGELOG.md

# Commit and tag
git add package.json CHANGELOG.md package-lock.json
git commit -m "chore(release): version $NEW_VERSION"
git tag -a "v$NEW_VERSION" -m "Release $NEW_VERSION"

echo "✅ Version bumped to $NEW_VERSION"

5. Changelog Generation

#!/bin/bash
# generate-changelog.sh

# Using conventional-changelog CLI
conventional-changelog -p angular -i CHANGELOG.md -s

# Or manually format changelog
CHANGELOG="# Changelog

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

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

## [Unreleased]

### Added
- New feature description

### Changed
- Changed feature description

### Deprecated
- Deprecated feature description

### Removed
- Removed feature description

### Fixed
- Bug fix description

### Security
- Security fix description

## [1.2.0] - 2024-01-15

### Added
- New search functionality
- Support for pagination

### Fixed
- Critical security vulnerability in authentication
- Memory leak in cache manager"

echo "$CHANGELOG" > CHANGELOG.md

6. GitHub Actions Release Workflow

name: Semantic Release
on: [push, workflow_dispatch]
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      - run: npm ci
      - run: npm test
      - run: npm run build
      - uses: cycjimmy/semantic-release-action@v3
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Best Practices

✅ DO

  • Follow strict MAJOR.MINOR.PATCH format
  • Use conventional commits
  • Automate version bumping
  • Generate changelogs automatically
  • Tag releases in git
  • Document breaking changes
  • Use prerelease versions for testing

❌ DON'T

  • Manually bump versions inconsistently
  • Skip breaking change documentation
  • Use arbitrary version numbering
  • Mix features in patch releases

Version Examples

1.0.0 → First release
1.1.0 → New feature
1.1.1 → Bug fix
2.0.0 → Breaking changes
2.0.0-beta.1 → Beta

Resources