Development Workflow

Manage Release Tags and Semantic Versioning

Create traceable releases with consistent version numbers, annotated tags, and clear compatibility signals.

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.
Share this page Help other developers discover this resource.