Skip to content

Draft — not approved. A working draft by UASK. It may change without notice.

Status: review · Version 1.0.0

Semantic versioning

Summary

Semantic Versioning (SemVer) gives every release a number MAJOR.MINOR.PATCH whose parts carry meaning: MAJOR for incompatible changes, MINOR for backward-compatible additions, PATCH for backward-compatible fixes. It only works if the project states what its public interface is, because “compatible” is measured against that interface. SemVer applies to libraries, APIs, themes, plugins, packages and documentation sets alike.

Rules

  • R1. A project that uses SemVer MUST declare its public interface — API, CLI, configuration format, file format, extension points or published rules — in code or documentation.
  • R2. A version MUST have the form X.Y.Z with non-negative integers without leading zeros.
  • R3. Once a version is released, its contents MUST NOT change; any change MUST be released as a new version. Release tags MUST NOT be moved or reused.
  • R4. MAJOR MUST be incremented for any backward-incompatible change to the public interface; MINOR and PATCH are then reset to 0.
  • R5. MINOR MUST be incremented for backward-compatible new functionality and when public functionality is marked deprecated; PATCH is then reset to 0.
  • R6. PATCH MUST be incremented for backward-compatible bug fixes only.
  • R7. Before 1.0.0 (major version zero) the interface MAY change at any time; a project that others depend on in production SHOULD release 1.0.0.
  • R8. Pre-release versions MUST use a hyphen suffix (2.1.0-rc.1) and MUST be treated as lower precedence than the matching release; build metadata (+build.7) MUST be ignored when comparing versions.
  • R9. Every release SHOULD have a human-readable changelog entry that groups changes and marks breaking changes and deprecations explicitly.
  • R10. A deprecated feature SHOULD remain available for at least one MINOR release before it is removed in a MAJOR release.

Guidance

  • Decide what is public. For a web theme or plugin, the public interface usually includes hooks, template variables, settings and CSS classes that others override — not only PHP or JavaScript functions.
  • When in doubt, it is MAJOR. If a reasonable user’s code or configuration can stop working, the change is breaking, even if it “fixes” a behaviour.
  • Accidental breaking release. Do not delete or re-tag it. Release a PATCH that restores compatibility and publish the breaking change later as a MAJOR.
  • Consumers. Pin exact versions in lock files for reproducible builds; use ranges (^2.3.0) only where a package manager resolves and records them in a lock file.
  • Changelog. Keep a Changelog’s categories — Added, Changed, Deprecated, Removed, Fixed, Security — map well onto SemVer; Conventional Commits can generate the draft.
  • Tags. Tag releases as vX.Y.Z in Git; the v is a tag convention, not part of the version.

Explanation

Without a shared meaning for version numbers, every upgrade requires reading code or release notes to find out whether it is safe. Teams then either freeze dependencies (and miss security fixes) or upgrade blindly (and break). SemVer turns the version into a promise about compatibility, which makes automated upgrades and dependency ranges safe to use.

Immutability (R3) is what makes the promise trustworthy: if 1.4.2 can mean different contents on different days, pinning it protects nobody. Precedence rules (R8) let tools sort versions consistently, including release candidates.

Examples

Good — the change decides the number:

From Change To
2.3.1 fix a wrong tax rounding 2.3.2
2.3.2 add an optional currency setting 2.4.0
2.4.0 mark legacy_checkout deprecated 2.5.0
2.5.0 remove legacy_checkout; rename a hook 3.0.0
3.0.0 release candidate of the next minor 3.1.0-rc.1 < 3.1.0

Bad — a renamed configuration key shipped as 2.4.1 “because it is small”; users upgrading a patch release find their configuration silently ignored.

Sources