When should I release a major version?

Release a major version when you make any breaking change: removing a public API, changing a function signature, altering behavior that consumers depend on, or dropping support for a platform/language version. Even seemingly small breaking changes warrant a major version bump in SemVer.

What does ^ mean in package.json?

The caret ^ allows changes that do not modify the left-most non-zero digit. ^1.2.3 accepts >=1.2.3 =0.2.3 <0.3.0. ^0.0.3 only accepts 0.0.3 exactly. This means npm update will take minor and patch updates but not a new major version.

What is the difference between 1.0.0-alpha and 1.0.0?

1.0.0-alpha is a pre-release version of 1.0.0 and has lower precedence: 1.0.0-alpha < 1.0.0. Pre-release identifiers (alpha, beta, rc) indicate unstable releases intended for testing. npm install will not install pre-release versions unless specified explicitly or with the --tag flag.

When should I release a major version?

Release a major version when you make any breaking change: removing a public API, changing a function signature, altering behavior that consumers depend on, or dropping support for a platform/language version. Even seemingly small breaking changes warrant a major version bump in SemVer.

What does ^ mean in package.json?

The caret ^ allows changes that do not modify the left-most non-zero digit. ^1.2.3 accepts >=1.2.3 =0.2.3 <0.3.0. ^0.0.3 only accepts 0.0.3 exactly. This means npm update will take minor and patch updates but not a new major version.

What is the difference between 1.0.0-alpha and 1.0.0?

1.0.0-alpha is a pre-release version of 1.0.0 and has lower precedence: 1.0.0-alpha < 1.0.0. Pre-release identifiers (alpha, beta, rc) indicate unstable releases intended for testing. npm install will not install pre-release versions unless specified explicitly or with the --tag flag.

What is Semantic Versioning? — SemVer Explained

Q: What is the difference between 1.0.0-alpha and 1.0.0?

1.0.0-alpha is a pre-release version of 1.0.0 and has lower precedence: 1.0.0-alpha < 1.0.0. Pre-release identifiers (alpha, beta, rc) indicate unstable releases intended for testing. npm install will not install pre-release versions unless specified explicitly or with the --tag flag.

Definition

Semantic Versioning (SemVer) is a versioning convention for software packages, defined at semver.org, that uses a MAJOR.MINOR.PATCH number scheme where each component has a specific semantic meaning. A version like 2.4.1 means major version 2, minor version 4, patch 1. The semantic rules tell consumers of a library what to expect when they upgrade: is this a breaking change? A new feature? A bug fix? Package managers like npm and Cargo use SemVer range operators to declare compatible version ranges.

How It Works

The three version components have strict rules: MAJOR is incremented when you make incompatible (breaking) API changes. MINOR is incremented when you add new functionality in a backward-compatible way. PATCH is incremented for backward-compatible bug fixes. Version 0.x.x is special — it is development status where anything may change at any time. Pre-release versions use hyphen suffixes (1.0.0-alpha.1, 2.0.0-rc.2). Build metadata uses + (1.0.0+build.42). npm uses ~ for patch ranges (equivalent to 1.2.x) and ^ for minor ranges (equivalent to 1.x.x).

Common Use Cases

▸Publishing npm packages with a clear contract about breaking changes
▸Declaring dependency version ranges in package.json with ^ and ~
▸Communicating API compatibility to consumers of a library
▸Automating changelog generation from conventional commit messages
▸Configuring automated dependency update tools like Dependabot

Example

2.4.1
│ │ └── PATCH: bug fixes, no API changes
│ └──── MINOR: new features, backward compatible
└────── MAJOR: breaking changes

npm ranges:
^1.2.3 → >=1.2.3 <2.0.0 (any compatible minor/patch)
~1.2.3 → >=1.2.3 <1.3.0 (only patch updates)
1.0.0-alpha.1 → pre-release version

Related Tools

vSemVer Validator

Validate semantic version strings and parse major, minor, patch, pre-release, and build metadata.

FAQ

When should I release a major version?: Release a major version when you make any breaking change: removing a public API, changing a function signature, altering behavior that consumers depend on, or dropping support for a platform/language version. Even seemingly small breaking changes warrant a major version bump in SemVer.
What does ^ mean in package.json?: The caret ^ allows changes that do not modify the left-most non-zero digit. ^1.2.3 accepts >=1.2.3 <2.0.0. ^0.2.3 accepts >=0.2.3 <0.3.0. ^0.0.3 only accepts 0.0.3 exactly. This means npm update will take minor and patch updates but not a new major version.
What is the difference between 1.0.0-alpha and 1.0.0?: 1.0.0-alpha is a pre-release version of 1.0.0 and has lower precedence: 1.0.0-alpha < 1.0.0. Pre-release identifiers (alpha, beta, rc) indicate unstable releases intended for testing. npm install will not install pre-release versions unless specified explicitly or with the --tag flag.

Related Terms

Regular Expression (Regex)Slug