-
Notifications
You must be signed in to change notification settings - Fork 11.9k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
9960a9e
commit 6501a44
Showing
1 changed file
with
64 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,64 @@ | ||
--- | ||
title: Introduction to Semantic Versioning (SemVer) | ||
shortTitle: Semantic Versioning (SemVer) explained | ||
type: story | ||
language: javascript | ||
tags: [node] | ||
author: chalarangelo | ||
cover: wet-lowland-golden-hour | ||
excerpt: Learn how semantic versioning works and how to use it to correctly version your software. | ||
dateModified: 2023-07-16T05:00:00-04:00 | ||
--- | ||
|
||
**SemVer** (short for **Semantic Versioning**) is a versioning scheme commonly used in software development to communicate the changes and **compatibility** of a software package. The JavaScript ecosystem, embodied mainly in the **npm package manager**, has adopted SemVer as the standard versioning scheme for JavaScript packages. The version of a package can be found in its `package.json` file, and it is also displayed in the npm registry. | ||
|
||
```json | ||
{ | ||
"name": "my-package", | ||
"version": "1.0.0" | ||
} | ||
``` | ||
|
||
### SemVer versions | ||
|
||
SemVer versions are formatted in **three numeric components**, as follows: | ||
|
||
``` | ||
{major}.{minor}.{patch} | ||
``` | ||
|
||
Each component represents a specific type of change made to the software. | ||
|
||
- **Major version**: Significant changes that may **break compatibility** with previous versions. Developers should carefully review the documentation and test their code against the new version before upgrading. | ||
- **Minor version**: Backwards-compatible **additions or improvements** that don't break compatibility with previous versions. Users can typically upgrade to a new minor version without worrying about major changes that might require code modifications. | ||
- **Patch version**: Backwards-compatible **bug fixes, patches, or maintenance** releases. Patch releases are intended to be safe and shouldn't introduce new features or breaking changes. | ||
|
||
The following table summarizes the different types of changes represented by each component: | ||
|
||
| Component | Type of change | Example | | ||
| --------- | -------------- | ------- | | ||
| Major | Incompatible | Breaking changes, rewrites, architectural changes | | ||
| Minor | Compatible | New features, functionalities, enhancements | | ||
| Patch | Compatible | Bug fixes, patches, maintenance releases | | ||
|
||
### Releases and pre-releases | ||
|
||
The **first version** of a software package is typically denoted as `1.0.0`. This is because the initial release of a software package is considered to be a major version, and the first version of a major version is always `1.0.0`. Versions starting with `0.x.x` are considered to be pre-release versions and are not intended for production use. | ||
|
||
Additionally, SemVer allows for **pre-release versions** to be appended to the version number. These are denoted by a hyphen followed by a series of alphanumeric identifiers, such as `1.0.0-alpha.1` or `1.0.0-beta.2`. Pre-release versions are typically used to indicate that the software is still under active development and may not be ready for production use. | ||
|
||
### Specifying which version to use | ||
|
||
When installing a package, you can specify which version to use by appending the version number to the package name, as follows: | ||
|
||
```shell | ||
npm install my-package@1.0.0 | ||
``` | ||
|
||
If you don't specify a version, npm will install the **latest version** of the package. You can also use the `^` or `~` symbols to specify a range of versions. For example, `^1.0.0` will install the latest version of the package that is compatible with `1.0.0`. Similarly, `~1.0.0` will install the latest version of the package that is compatible with `1.0.0` and has the same major version. Here's a quick summary of the different ways to specify a version: | ||
|
||
- Exact version: `1.0.4` | ||
- Patch releases: `1.0` or `1.0.x` or `~1.0.4` | ||
- Minor releases: `1` or `1.x` or `^1.0.4` | ||
|
||
Note that you can also change the version of each dependency by editing the `package.json` file directly. Just remember to run `npm install` after making any changes to the `package.json` file. |