Semantic Release — The Version Bump That Skipped From v1.2.3 to v2.0.0

Semantic versioning (semver) is the convention: MAJOR.MINOR.PATCH. semantic-release automates the versioning decision based on commit messages. This eliminates human error in version bumps, ensures every merge to main can produce a release, and generates changelogs automatically. The key requirement: your team must use conventional commits. This guide covers setup, the incident where a mislabeled commit would have caused a silent major version bump, and how to configure semantic-release for your project.

Setting Up semantic-release

Install: npm install -g semantic-release or npm install --save-dev semantic-release.

Configure: create .releaserc (JSON or YAML) with branches, plugins, and publish options.

Plugins: @semantic-release/commit-analyzer (analyzes commits for version), @semantic-release/release-notes-generator (generates changelog), @semantic-release/npm (publishes to npm), @semantic-release/github (creates GitHub release), @semantic-release/git (commits changelog to repo).

CI setup: Add a semantic-release step to your CI pipeline that runs after tests pass on main. Use npx semantic-release with a GITHUB_TOKEN environment variable.

Dry run: npx semantic-release --dry-run shows the next version number and changelog without publishing.

# Install semantic-release
npm install -g semantic-release

# Create config file
cat > .releaserc << 'EOF'
{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    "@semantic-release/github"
  ]
}
EOF

# Dry run to preview
npx semantic-release --dry-run

# Run in CI (example: GitHub Actions step)
# - run: npx semantic-release
#   env:
#     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
#     NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

# Verify the release version
npx semantic-release --dry-run 2>&1 | grep 'next version'