---

name: semver-automation compatibility: opencode completeness: 95 content-types:

• code
• guidance
• do-dont
• examples description: '"Provides Automating semantic versioning in Git repositories for version bumping, changelog generation, and release automation using conventional commits and to"' license: MIT maturity: stable metadata: domain: coding output-format: code related-skills: cve-dependency-management, git-advanced, git-branching-strategies, javascript-package-workflows role: implementation scope: implementation triggers: semantic versioning, semver, version bumping, conventional commits, semantic-release, changelog automation, release automation, git tags archetypes:
  • tactical
  • generation anti_triggers:
  • brainstorming
  • vague ideation
  • code golf
  • over-engineering response_profile: verbosity: low directive_strength: high abstraction_level: operational version: "1.0.0"

---

Semantic Versioning Automation

Implementation guide for automating semantic versioning in Git repositories using conventional commits and release automation tools like semantic-release, including version bumping, changelog generation, and release workflows.

TL;DR Checklist

• Establish conventional commit format (feat:, fix:, BREAKING CHANGE:) for all commits
• Configure semantic-release or similar tool in CI/CD pipeline
• Set up automatic version bumping based on commit types
• Generate changelogs automatically from commit messages
• Create and push Git tags for each release
• Publish artifacts and update version files automatically

---

When to Use This Skill

Use semver automation when:

• Managing public libraries or frameworks with semantic versioning contract
• Running continuous deployment with frequent releases
• Multiple teams need consistent versioning across services
• You want to reduce human error in version management
• Changelogs should reflect actual commit history
• Teams need clear communication about breaking changes
• Automating release notes and changelog generation

---

When NOT to Use This Skill

Avoid full automation when:

• Monolithic product with infrequent (quarterly) releases
• Version numbers have business meaning beyond semver (e.g., "Q3 2026.1.0")
• Manual changelog curation is important (mixed with non-code changes)
• Organization prefers explicit version decisions (no automatic bumping)
• Repository has inconsistent or legacy commit practices

---

Semantic Versioning Format

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Examples:
1.0.0        - First stable release
1.2.3        - Patch fix (1.2.2 → 1.2.3)
2.0.0        - Breaking change (1.x.x → 2.0.0)
2.0.0-rc.1   - Release candidate
2.0.0-alpha  - Alpha release
2.0.0+build-123  - Build metadata

Increment rules:
MAJOR when:   Breaking changes / incompatible API changes
MINOR when:   New features (backward-compatible)
PATCH when:   Bug fixes (backward-compatible)

---

Conventional Commits

Format

<type>(<scope>): <subject>

<body>

<footer>

Commit Types

Type	Meaning	Bumps
feat	New feature	MINOR
fix	Bug fix	PATCH
docs	Documentation only	None
style	Code formatting (no logic change)	None
refactor	Code refactoring	None
perf	Performance improvement	PATCH
test	Test additions or changes	None
chore	Build, deps, tooling	None

Breaking Changes

# Commit message that triggers MAJOR version bump
feat(api): change response format

BREAKING CHANGE: response structure changed from {id, name} to {identifier, full_name}

# Or footer notation
feat!: redesign API endpoint structure

# Or type! notation
feat!: remove deprecated authentication method

Examples

# Feature commit (MINOR bump)
git commit -m "feat(auth): add two-factor authentication support

- Implement TOTP-based 2FA
- Update user settings UI
- Add 2FA recovery codes"

# Bug fix (PATCH bump)
git commit -m "fix(api): handle null responses in payment gateway"

# Breaking change (MAJOR bump)
git commit -m "feat(api)!: change authentication header format

BREAKING CHANGE: Authorization header changed from 'Bearer token' to 'Token token'"

# No version bump
git commit -m "docs(readme): improve installation instructions"

---

Semantic-Release Setup

Installation & Configuration

# Install semantic-release and plugins
npm install --save-dev semantic-release @semantic-release/changelog @semantic-release/git @semantic-release/npm

# Or with yarn
yarn add --dev semantic-release @semantic-release/changelog @semantic-release/git @semantic-release/npm

Configuration File (.releaserc.json)

{
  "branches": [
    "main",
    {
      "name": "develop",
      "prerelease": "rc"
    }
  ],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@semantic-release/changelog",
      {
        "changelogFile": "CHANGELOG.md"
      }
    ],
    "@semantic-release/npm",
    [
      "@semantic-release/git",
      {
        "assets": [
          "package.json",
          "CHANGELOG.md",
          "src/version.ts"
        ],
        "message": "chore(release): v${nextRelease.version}\n\n${nextRelease.notes}"
      }
    ],
    "@semantic-release/github"
  ],
  "preset": "angular"
}

CI/CD Integration (GitHub Actions)

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

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
      id-token: write

    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v3
        with:
          node-version: 18

      - run: npm ci

      - run: npm run build

      - run: npm test

      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

---

Manual Version Management

If Not Using Automation

# Manual version bump in package.json
# Old: "version": "1.2.3"
# New: "version": "1.2.4"

npm version patch   # Auto bumps PATCH version
npm version minor   # Auto bumps MINOR version
npm version major   # Auto bumps MAJOR version

# Creates Git tag and commit automatically
# Then push:
git push origin main --tags

Generate Changelog Manually

# Using conventional-changelog CLI
npm install --save-dev conventional-changelog-cli

# Generate changelog from commits since last tag
npx conventional-changelog -p angular -r 2 -o CHANGELOG.md

# Or for the first time:
npx conventional-changelog -p angular -i CHANGELOG.md -s

# Commit and tag
git add CHANGELOG.md package.json
git commit -m "chore(release): v1.3.0"
git tag v1.3.0
git push origin main --tags

---

Release Workflows

Workflow 1: Automatic Release from main

# 1. Developer commits using conventional commits
git commit -m "feat(api): add user profile endpoint"

# 2. Push to main
git push origin main

# 3. CI/CD runs semantic-release automatically
#    - Analyzes commits since last tag
#    - Bumps version (1.2.0 → 1.3.0)
#    - Generates changelog
#    - Creates release notes
#    - Pushes Git tag
#    - Publishes to npm

# 4. GitHub release is created automatically

Workflow 2: Pre-release from develop

# Development branch uses pre-release versioning
# .releaserc.json has:
# "branches": ["main", {"name": "develop", "prerelease": "rc"}]

git checkout develop
git commit -m "feat: new experimental feature"
git push origin develop

# semantic-release creates v1.3.0-rc.1 (release candidate)
# Version: 1.3.0-rc.1, 1.3.0-rc.2, etc.
# Pre-releases don't update 'latest' tag

Workflow 3: Release from Feature Branch

# For scheduled releases or managed releases
git checkout -b release/1.3.0

# Fix any last-minute bugs
git commit -m "fix: critical security issue"

# Merge to main with special commit
git checkout main
git merge release/1.3.0 -m "chore(release): merge release/1.3.0"

# semantic-release detects merge and creates tag
git push origin main

# Delete release branch
git branch -d release/1.3.0

---

Changelog Generation

Generated Changelog Example

# [1.3.0](https://github.com/org/repo/compare/v1.2.0...v1.3.0) (2026-04-24)

### Features

- **api**: add user profile endpoint ([abc1234](https://github.com/org/repo/commit/abc1234))
- **auth**: implement refresh token rotation ([def5678](https://github.com/org/repo/commit/def5678))

### Bug Fixes

- **payment**: handle null payment gateway responses ([789abcd](https://github.com/org/repo/commit/789abcd))

### BREAKING CHANGES

- **auth**: authentication header format changed from 'Bearer token' to 'Token token'

---

# [1.2.0](https://github.com/org/repo/compare/v1.1.0...v1.2.0) (2026-04-17)

### Features

- **database**: add connection pooling ([fed4321](https://github.com/org/repo/commit/fed4321))

Custom Changelog Template

// conventional-changelog-config.js
module.exports = {
  types: [
    { type: 'feat', section: 'Features', hidden: false },
    { type: 'fix', section: 'Bug Fixes', hidden: false },
    { type: 'perf', section: 'Performance', hidden: false },
    { type: 'docs', section: 'Documentation', hidden: true },
    { type: 'style', section: 'Code Style', hidden: true },
    { type: 'refactor', section: 'Refactoring', hidden: true },
    { type: 'test', section: 'Tests', hidden: true },
    { type: 'chore', section: 'Chores', hidden: true }
  ],
  commitUrlFormat: '{{host}}/{{owner}}/{{repository}}/commit/{{hash}}',
  compareUrlFormat: '{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}'
};

---

Version Sync Across Files

Automatic File Updates

# .releaserc.json with git plugin
"@semantic-release/git": {
  "assets": [
    "package.json",
    "package-lock.json",
    "pyproject.toml",
    "src/version.ts",
    "src/version.py"
  ],
  "message": "chore(release): v${nextRelease.version}"
}

Version Files

// src/version.ts
export const VERSION = "1.3.0";
export const BUILD_DATE = "2026-04-24T10:30:00Z";

# src/version.py
VERSION = "1.3.0"
BUILD_DATE = "2026-04-24T10:30:00Z"

---

Constraints

MUST DO

• Use conventional commit format consistently across team (enforce in pre-commit hooks)
• Document breaking changes explicitly in commit footer (BREAKING CHANGE:)
• Test release process in dry-run mode before enabling in CI/CD
• Keep CHANGELOG.md updated before each release
• Tag every release with Git tags (v1.2.3 format)
• Verify version consistency across all files after release

MUST NOT DO

• Never manually edit generated changelogs (regenerate from commits instead)
• Never skip tests before automatic release
• Never mix manual and automatic versioning in same repository
• Never commit version bumps without corresponding feature/fix commits
• Never tag pre-releases as latest (use pre-release identifiers)

---

Related Skills

Skill	Purpose
coding-git-advanced	Git operations like tagging and rebasing used in release workflows
coding-git-branching-strategies	Release branch strategies that work with semver automation