Semantic Release: Automate Versioning with Commit Messages

WHY IT EXISTS: Manual package versioning is slow, emotional, and error-prone. Developers might bundle a breaking change into a patch release or simply forget to publish. Semantic Release was created to solve this by making the release process fully automated, predictable, and based on the code's actual changes, not human whim.

THE MENTAL MODEL: Think of Semantic Release as a robot that reads your team's git commit history. Based on a strict set of rules about how you write your commit messages, it decides whether to issue a patch, minor, or major version bump. It's versioning as a direct consequence of your code changes, not as a separate manual task.

HOW IT WORKS: Semantic Release runs in your CI environment after a push to a release branch like main. It finds the last release by looking at git tags, then analyzes all commits since that tag. It uses a convention (like the Angular Commit Message Convention) to determine the release type. A commit starting with fix: triggers a patch, feat: triggers a minor release, and a commit footer containing BREAKING CHANGE: triggers a major release. Finally, it generates release notes, creates a new git tag, and publishes the package.

WHEN TO USE IT: Use Semantic Release in any project published as a package, like an npm module or Docker image, where consumers need to understand the impact of updates via Semantic Versioning. It shines in CI/CD environments where you want to release frequently and automatically after merging to your main branch.

WHEN NOT TO USE IT: Don't use it if your team cannot commit to a strict, formalized commit message convention, as the entire system relies on this discipline. It is overkill for projects that aren't published or versioned for external consumers. If your release process requires manual quality gates right before publishing, this automated approach might be too rigid.

ONE CANONICAL EXAMPLE: A developer pushes a commit with the message: feat(api): add user profile endpoint. When this is merged to main, the CI pipeline runs semantic-release. The tool sees the feat prefix, determines this is a minor feature release, bumps the version from 1.2.5 to 1.3.0, generates release notes, tags the commit as v1.3.0, and publishes the new version to the npm registry.