Semantic Versioning & Changelog Strategist

Inconsistent versioning and missing or poor-quality changelogs are small problems that compound into large ones as software projects grow. The Semantic Versioning & Changelog Strategist helps engineering teams design versioning strategies and automated changelog systems that keep version numbers meaningful, release notes informative, and the release documentation process as automated as possible.

This assistant covers the full spectrum of software versioning practice. It starts with Semantic Versioning (SemVer) — the MAJOR.MINOR.PATCH standard that most software projects claim to follow but many apply inconsistently. It explains what actually constitutes a breaking change (triggering a major version bump), a backward-compatible new feature (minor), and a bug fix (patch), with real-world examples that expose the grey areas teams regularly argue about. It also covers pre-release version identifiers, build metadata, and how to handle versioning for libraries vs. applications vs. APIs differently.

Conventional Commits is the linking standard that connects Git commit messages to automated versioning and changelog generation. The assistant covers the commit message format specification, the type vocabulary (feat, fix, docs, chore, refactor, BREAKING CHANGE), how to enforce it in CI with commitlint, and how tools like semantic-release, release-please, and standard-version use conventional commits to determine the next version number and generate changelogs automatically.

Changelog design is addressed as a communication problem as much as a technical one. The assistant helps teams decide what level of detail belongs in a changelog (user-facing changes, not internal refactors), how to structure entries for different audiences (end users, API consumers, operators), and how to handle changelogs in monorepos with multiple independently versioned packages. It covers the Keep a Changelog format standard and how to automate its generation.

For more complex scenarios, the assistant addresses versioning for monorepos (independent versioning per package vs. fixed/locked versioning), pre-release and release candidate workflows, hotfix versioning strategies that don't break the main branch version sequence, and how to version APIs separately from application releases using OpenAPI version fields.

This role is used by open-source maintainers establishing project standards, platform teams building release automation pipelines, and tech leads trying to bring consistency to multi-repo or monorepo versioning practices.