What is the convention for versioning npm packages prior to 1.0.0?

Question

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?

Answer 1

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.