Learn Semantic Release - Core Concepts & Main Architecture

#Introduction

In episode 1 we agreed that commit history can be the source of truth for deciding versions. Now the question shifts: how exactly? The answer lies in two things that form the foundation of semantic-release's architecture: Semantic Versioning (SemVer) as the language of versions, and the commit analyzer as the brain that translates commits into release decisions.

Imagine semantic-release as a factory receptionist reading the workers' daily notes. Every note is formatted, so it knows: "there's a new feature" means the serial number goes up one minor level, "there's a bug fix" goes up one patch level, and "there's a major change" goes up one major level. That whole process is written in code, not oral policy.

#Main Discussion

#SemVer: The Language of Versions

Semantic Versioning gives meaning to the MAJOR.MINOR.PATCH version numbers:

MAJOR: backward-incompatible (breaking) changes.
MINOR: backward-compatible new features.
PATCH: backward-compatible bug fixes.

Version bump rules

1.0.0  -> 1.1.0      (minor: new feature)
1.1.0  -> 1.1.1      (patch: bug fix)
1.1.1  -> 1.2.0-rc.1 (rc prerelease)
1.2.0-rc.1  -> 1.2.0 (stable after rc passes)

Prereleases are written with a suffix such as 1.2.0-rc.1 and have lower precedence than stable 1.2.0. It's this property that the staging branch exploits to test release candidates before they go up to main.

#Commit Analyzer: The Translation Brain

The commit analyzer reads the commits since the last release tag and determines the release type: major, minor, patch, or no release at all.

The commit analyzer computes the release type from the commit window

v1.0.0 (last release tag)
   |
   +-- fix: fix email validation     -> patch
   +-- feat: add login page          -> minor
   |
v1.1.0 (next version)

The release version is determined by the highest commit type in that window: a single feat bumps minor, a single breaking change bumps major. If there is no feat, fix, or breaking change, there is no new release — changelog, tag, and publish are all skipped.

#Pipeline Structure

A healthy release isn't triggered the moment a commit is pushed. A layered pipeline makes sure only code that passes verification gets released.

A healthy pipeline: lint -> build -> dry run -> release

npm run lint
npm run build
npx semantic-release --dry-run --no-ci
npx semantic-release

Lint and build run quality assurance on every pull request — before anything is released.
Dry run shows what would happen with no side effects at all. It's the best safety net.
Release only runs on allowed branches, using the results of the commit analysis.

#The Nine Plugin Pipeline Steps

Each plugin implements one or more steps. The whole release flows through the following sequence:

The semantic-release pipeline steps

1 verifyConditions
2 analyzeCommits
3 verifyRelease
4 generateNotes
5 prepare
6 publish
7 addChannel
8 success
9 fail

Explanation of each step:

verifyConditions: plugins verify prerequisites — the token is available, the registry is reachable, the environment is correct.
analyzeCommits: the commit analyzer computes the release type from commit history.
verifyRelease: final validation before the version is written, e.g. making sure the release type isn't null.
generateNotes: release-notes-generator assembles the changelog from the classified commits.
prepare: plugins write the new version into files — package.json, CHANGELOG.md, or other artifacts.
publish: uploads the release result — npm publish, or creating a GitHub Release.
addChannel: adds the release to a channel, used for prereleases on additional branches.
success: notifies other parties that the release succeeded, e.g. a comment on a PR.
fail: runs when an error occurs, usually creating an issue or a failure report.

#Core Plugins

Plugin	Main Step	Primary Task
commit-analyzer	analyzeCommits	Determine the release type from commits
release-notes-generator	generateNotes	Assemble the changelog
npm	verifyConditions, prepare, publish	Update package.json + publish to registry
github	verifyConditions, publish, success, fail	GitHub Release + PR comments + issues
git	prepare	Commit the prepare results + create the tag

The git + npm combination is the most commonly used pairing: git commits the prepare results (new versions in package.json and CHANGELOG.md) and creates the tag, then npm publishes the package. This blog repo uses all five core plugins — feel free to open release.config.cjs and compare it with the table above.

Tip

Before enabling a real release, get into the habit of running npx semantic-release --dry-run --no-ci first. Its output shows the version that would be created, the changelog that would be generated, and which plugins would run — without touching git or the registry.

#Conclusion

In episode 2 you learned:

SemVer rules: major for breaking, minor for features, patch for bugs, with an rc suffix for prereleases.
The commit analyzer determines the release type from the highest commit type in the release window.
A healthy pipeline: lint, build, dry run, then release.
The nine plugin pipeline steps, from verifyConditions through fail.

In episode 3 we'll focus on the language the commit analyzer reads: Conventional Commits — the type(scope): subject format, the common type list, and how to mark breaking changes. See you in episode 3!