Semantic Versioning Rules

MAJOR.MINOR.PATCH — e.g. 2.4.1

Change type	Number to bump	Example
Backward-compatible bug fix	PATCH	2.4.1 → 2.4.2
Backward-compatible feature	MINOR	2.4.1 → 2.5.0
Breaking change	MAJOR	2.4.1 → 3.0.0

Before 1.0.0 is initial development (breaking changes are allowed)
Pre-release: 1.0.0-alpha.1, 1.0.0-beta.2
Build metadata: 1.0.0+20250527

Conventional Commits Format

CODE

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

[body]

[footer]

Types:

Type	Meaning	Version impact
feat	New feature	MINOR
fix	Bug fix	PATCH
docs	Documentation only	-
style	Formatting (no functional change)	-
refactor	Code cleanup with no functional change	-
perf	Performance improvement	PATCH
test	Add or update tests	-
chore	Build or config changes	-
ci	CI config changes	-
BREAKING CHANGE	Not backward compatible	MAJOR

Bash

# example
git commit -m "feat(auth): add OAuth2 login"
git commit -m "fix(api): fix timeout error"
git commit -m "feat!: remove the existing API"
# or in the footer
git commit -m "feat: new authentication method

BREAKING CHANGE: /api/v1/login endpoint removed"

Automated releases with standard-version

Bash

npm install --save-dev standard-version

JSON

// package.json
{
  "scripts": {
    "release": "standard-version",
    "release:minor": "standard-version --release-as minor",
    "release:major": "standard-version --release-as major",
    "release:patch": "standard-version --release-as patch"
  }
}

Bash

# Automatically bump the version, generate CHANGELOG, and create a git tag
npm run release

# Dry run (preview without making changes)
npx standard-version --dry-run

# Push tags
git push --follow-tags

Automated releases with GitHub Actions

YAML

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

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0      # full history required

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Configure Git
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Release
        run: |
          npm ci
          npx standard-version
          git push --follow-tags
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Example CHANGELOG.md output

MARKDOWN

# Changelog

## [2.5.0] - 2025-05-27
### Features
- **auth:** add OAuth2 login (abc1234)

### Bug Fixes
- **api:** fix timeout error (def5678)

## [2.4.2] - 2025-05-20
### Bug Fixes
- **db:** fix connection leak (ghi9012)

#semver#conventional-commits#changelog#git

Editorial note

AI tools may assist drafting. Check the evidence in each guide for whether commands were run and which environment was used. Confirm the current docs for your version before applying instructions, and email us about errors. email us

Topic-related official docs (auto-linked · not per-claim sources)Git documentation ↗

How we write and review →Editorial policy →

Questions & answers

Ask a question about this guide. We'll review and reply.

Semantic Versioning + Conventional Commits + Automated CHANGELOG

Semantic Versioning Rules

Conventional Commits Format

Automated releases with standard-version

Automated releases with GitHub Actions

Example CHANGELOG.md output

Questions & answers