A release version communicates change to users, operators, and downstream developers. Semantic Versioning is useful when a project has a defined public compatibility contract.
Apply version numbers consistently
For a SemVer-compatible project, major versions indicate incompatible public API changes, minor versions add backward-compatible functionality, and patch versions contain backward-compatible fixes. Pre-release identifiers can distinguish preview builds.
Do not label every internal deployment as a public release unless users benefit from that distinction.
Tag the source precisely
Create release tags on the commit that represents the shipped source. Annotated tags can include metadata and a message. Protect release tags from accidental movement or deletion.
Publish useful release notes
Summarize user-visible changes, breaking changes, security fixes, migrations, and upgrade steps. Link to relevant issues or pull requests without exposing private information.
Checklist
- Define what compatibility promise versions represent.
- Tag the exact released commit.
- Protect release tags.
- Document breaking changes and upgrade steps.
- Keep release notes useful to operators and users.