Version Specifications Documentation

When specifying versions for packages or modules, you may encounter various formats. Below are the details and examples to help you understand and apply the correct version specifiers.

---

General Form

Semantic Versioning Explained

Semantic Versioning uses a three-part version number along with optional labels to indicate pre-release or build metadata. The basic format is as follows:

major.minor.patch

For example:
1.2.3

Each part has its own meaning:

Part	Position	Meaning	Example from 1.2.3
major	1st	Incompatible API changes; signals breaking changes.	1
minor	2nd	Backward-compatible functionality additions or changes.	2
patch	3rd	Backward-compatible bug fixes and minor improvements.	3

---

Pre-release and Additional Labels

Sometimes, a version may include an additional pre-release label. The format for a pre-release version is:

major.minor.patch-label.identifier

For example, the version "1.2.3-beta.2" can be broken down as:

Segment	Explanation	Example from 1.2.3-beta.2
major.minor.patch	The basic semantic version, as described above.	1.2.3
label (e.g., beta)	Indicates the type of pre-release (e.g., alpha, beta, rc).	beta
identifier (e.g., 2)	Provides additional ordering within pre-release versions.	2

These pre-release versions allow you to test or preview new features before finalizing a production release.

---

Version Examples Recap

1. Basic Release:
   Version: 1.2.3

   • Major: 1
   • Minor: 2
   • Patch: 3

2. Pre-release/Beta Version:
   Version: 1.2.3-beta.2

   • Major: 1
   • Minor: 2
   • Patch: 3
   • Pre-release label: beta
   • Pre-release identifier: 2

---

Version Prefixes

When specifying version ranges or constraints, prefixes can be used to indicate which versions are acceptable. Below are common prefixes, their meanings, and examples.

Value	Description	Example (Assuming current version: 1.2.3)
~version	Include everything greater than or equal to the specific version in the same minor range.	~1.2.3 includes versions 1.2.3, 1.2.4, …, up to but not including 1.3.0
^version	Include everything greater than or equal to the specific version in the same major range.	^1.2.3 includes versions from 1.2.3 up to, but not including, 2.0.0.
version	Must match the version exactly.	1.2.3 only accepts version 1.2.3.
>version	Must be strictly greater than the specified version.	>1.2.3 accepts versions higher than 1.2.3.
>=version	Must be greater than or equal to the specified version.	>=1.2.3 accepts 1.2.3 and any higher version.
<version	Must be strictly less than the specified version.	<1.2.3 accepts versions lower than 1.2.3.
<=version	Must be less than or equal to the specified version.	<=1.2.3 accepts 1.2.3 and any lower version.
1.2.x	Accepts any patch version within the minor version.	1.2.x is equivalent to 1.2.* (i.e., 1.2.0, 1.2.1, 1.2.2, etc.) but not 1.3.0 or 1.1.9.
*	Matches any version.	* will match all available versions.
latest	Indicates the latest release is desired.	latest always points to the most recent official release.

Additional Specifiers

Besides the above list, version specifiers can also include:

• GitHub URLs: Directly referencing specific GitHub repositories.
• GitHub User Repositories: Referencing tags or commits from a user’s repository.
• Local Paths: Referencing local files or directories (commonly used in development environments).
• NPM Tags: Using tags like next, beta, rc, or any custom tag as specified by npm maintainers.

---

Examples in Context

1. Using tilde (~) in a package.json (npm example):

   Suppose you have a dependency on package "example-package" and you want to allow updates within the same minor version:

   {
     "dependencies": {
       "example-package": "~1.2.3"
     }
   }

   This will include updates such as 1.2.4 or 1.2.5, but will not include 1.3.0.

2. Using caret (^) to allow major range updates:

   Specifying a dependency that allows updates within the same major version:

   {
     "dependencies": {
       "example-package": "^1.2.3"
     }
   }

   This will include versions like 1.3.0 or 1.4.2, but will refuse upgrades to 2.0.0.

3. Exact version requirement:

   Often used when you need to lock down a specific version:

   {
     "dependencies": {
       "example-package": "1.2.3"
     }
   }

4. Pre-release version with a beta tag:

   This is useful for accessing beta releases:

   {
     "dependencies": {
       "example-package": "1.2.3-beta.2"
     }
   }

5. Wildcard usage:

   When you want to allow all versions:

   {
     "dependencies": {
       "example-package": "*"
     }
   }

6. Using a comparison operator:

   To include only versions greater than a specific release:

   {
     "dependencies": {
       "example-package": ">1.2.3"
     }
   }