Skip to main content
This article explains how module version numbering communicates stability and backward-compatibility guarantees. A module’s version string helps both consumers and authors decide whether an upgrade is safe, and which releases introduce new features, bug fixes, or breaking changes.
Read version numbers before upgrading a dependency. Proper versioning signals what to expect from a release: new features, bug fixes, or breaking changes.
A dark presentation slide titled "Module version numbering." It contains two bullet points explaining that a module's version number signals its stability/backward compatibility and that each release number reflects the nature of changes since the previous release.
When you depend on external modules, inspect their version numbers to evaluate stability before upgrading. When publishing your own module, pick version numbers that accurately reflect the compatibility guarantees you intend to provide. Most modules follow semantic versioning (semver). The common format is MAJOR.MINOR.PATCH, optionally suffixed with a pre-release identifier (for example, v1.4.0-beta.2). Each segment conveys a distinct meaning:
  • MAJOR: breaking changes to the public API (not backward compatible)
  • MINOR: new features that remain backward-compatible
  • PATCH: backward-compatible bug fixes and small improvements
Below is a visual highlighting the major version component.
A presentation slide titled "Module version numbering" showing the version string "v1.4.0 – beta.2" with the "1" highlighted and labeled "major version."
A change in the major number signals incompatible API changes. Consumers should treat major-version upgrades as potentially breaking and plan accordingly (read CHANGELOGs, run tests, and check migration notes). Here is the minor version explanation with the corresponding diagram.
A dark presentation slide titled "Module version numbering" showing the version string "v 1.4.0 - beta.2" with the "4" highlighted and labeled "minor version."
Increment the minor version to add new, backward-compatible features or improvements. Minor releases are intended to be safe upgrades for existing consumers. This diagram highlights the patch segment.
A slide titled "Module version numbering" showing the example version string "v 1.4.0 - beta.2" with the final 0 highlighted and labeled "patch version." The slide has a dark background with teal and purple highlights.
Patch releases contain bug fixes and small, backward-compatible changes. These should be the least risky upgrades and typically don’t require code changes. Summary table Important notes about special cases:
  • Versions with a major version of zero (v0.x) indicate initial development. Authors may introduce breaking changes in minor or patch releases during this phase.
  • Pre-release identifiers (for example, alpha, beta, rc) mark releases that are not final and do not carry the same stability guarantees as final releases.
v0.x releases are considered unstable. Authors can introduce breaking changes in minor or patch updates during initial development — consumers should be cautious when depending on v0 modules.
Example of a pre-release notation:
Further reading and references That covers the essentials of module version numbering and what each segment of a semantic version communicates. Follow semantic versioning practices to set clear expectations for your users and to evaluate dependency upgrades safely.

Watch Video