42

I was reading up on versioning with npm, and apparently it provides a nice convenient command for bumping your package versions.

npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease]

prerelease

Lets say your package starts at version 0.0.0

npm version prerelease => 0.0.1-0

npm version prerelease => 0.0.1-1

Basically just bumps the number after the dash

prepatch

Starting from 0.0.0 using pre[major|minor|patch] instead...

npm version prepatch => 0.0.1-0

npm version preminor => 0.1.0-0

npm version premajor => 1.0.0-0

patch

Starting from 0.0.0 using patch...

npm version patch => 0.0.1

npm version patch => 0.0.2

I understand the rules for bumping major minor and patch versions, but what is the standard convention for versioning things prior to 1.0.0?

SteamDev
  • 4,294
  • 5
  • 20
  • 29
  • 3
    What don't you get? Didn't you just literally explain how it works? – Brian Noah Feb 10 '15 at 00:20
  • 1
    @BrianNoah I understand how the CLI works, my question is what is the significance of `0.0.1-0`, `0.0.1-1`, etc versus `0.0.1`, `0.0.2`, etc when you're in the pre 1.0 phase. – SteamDev Feb 10 '15 at 15:34

1 Answers1

42

TLDR

I have not seen prelease versions utilized pre-1.0.0. It seems fairly pointless since the public API is not finalized yet. They become useful after 1.0.0 is released.

So when are prelease versions useful?

From semver.org:

Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.

and:

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. ...A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version.

The conventions I have seen pre-1.0.0 include using patches for bug fixes/typos and minor versions for any significant modifications. The conventions are less strict pre-1.0.0 since no public API has been guaranteed yet.

Prelease versions come in handy when you want to share some early features with the community.

For example, at the time of this writing, the latest stable release of npm-check-updates is version 1.5.1. Some of the new features I have added have introduced backward-incompatible changes, so to conform to semver I will have to release them under 2.0.0. Yet, I don't want to release 2.0.0 as the latest stable version until it has been more thoroughly tested by the community. Thus, I have published a prerelease version (using npm publish --tag unstable) versioned at 2.0.0-alpha.1. Community members can install the prerelease version (with npm install -g npm-check-updates@unstable) to try out the latest features while a normal npm install -g npm-check-updates will continue to install the stable 1.5.1 version for most users. When the prerelease has proven itself, I can easily publish it as the new stable at 2.0.0.

Raine Revere
  • 30,985
  • 5
  • 40
  • 52
  • Great response and answer. I cleared up to me that I should be the prerelease and prepatch with grunt-bump. Thanks. – lislis Jun 02 '15 at 20:47
  • This is really helpful. Question, what happens if you have a prerelease (patch) that ends up conflicted on master due to hotfix (e.g. 1.4.1-alpha1, 1.4.1-alpha2 but then master needs bumping from 1.4.0 to 1.4.1 in a parrallel hotfix)? – Paul Grimshaw Oct 14 '20 at 15:47
  • @PaulGrimshaw I would suggest publishing `1.4.1` and `1.4.2-alpha1`. Thus `1.4.2-alpha1` represents the alpha release that will be released as `1.4.2` when it's ready for `latest`. – Raine Revere Oct 14 '20 at 17:27
  • 2
    So assuming you had an existing `1.4.1-alpha1` you would re-release this as `1.4.2-alpha1` – Paul Grimshaw Oct 14 '20 at 19:46