glossary

Semantic Versioning

A versioning scheme using a MAJOR.MINOR.PATCH number format where each component increments according to the nature of the changes: breaking changes, new features, and bug fixes respectively.

explanation

Semantic Versioning (SemVer), defined at semver.org, specifies that a version number takes the form MAJOR.MINOR.PATCH. MAJOR is incremented for incompatible API changes, MINOR for new backwards-compatible functionality, and PATCH for backwards-compatible bug fixes. Pre-release labels (1.0.0-alpha.1) and build metadata (1.0.0+build.1) are also supported. The direct connection between Conventional Commits and SemVer is one of the key motivations for the specification. Automated release tools like semantic-release and release-please read the commit history, identify the highest-impact change type (breaking change > feat > fix), and compute the next SemVer accordingly. This removes the manual decision of which version number to use next. For library authors, SemVer communicates contract stability to downstream consumers. A MAJOR bump signals that consumers must make changes; a MINOR bump adds capability without breaking anything; a PATCH bump is safe to apply without testing changes in consuming code.

examples

feat!: remove deprecated v1 API endpoints # triggers MAJOR bump

feat(payment): add Apple Pay integration # triggers MINOR bump

fix(checkout): correct tax rounding on fractional cents # triggers PATCH bump

chore(deps): upgrade dev dependencies # no version bump

how git-agent helps

git-agent ensures your commit history speaks SemVer accurately. By generating correctly typed conventional commits, it gives semantic-release and release-please the signal they need to compute the right version bump automatically.

brew install gitagenthq/tap/git-agent

FAQ

How does git-agent signal a breaking change?

When the LLM detects an incompatible API change in the diff, git-agent adds a BREAKING CHANGE: footer to the commit body and uses a ! immediately before the colon (after optional scope), e.g. feat(api)!: remove /v1 endpoints.

Does git-agent integrate with semantic-release or release-please?

git-agent is not directly integrated with those tools, but the commits it produces are fully compatible with both. They parse standard Conventional Commits format which git-agent outputs.

Should every commit type affect the version number?

No. Only feat, fix, and commits with BREAKING CHANGE footers affect version numbers in the standard semantic-release configuration. Types like chore, docs, style, and test do not trigger version bumps.

Conventional Commits Conventional changelog Breaking change template