A tag name is free text, but tools and people expect Semantic Versioning (SemVer 2.0.0, semver.org (https://semver.org/ 15,804 )): MAJOR.MINOR.PATCH, optionally followed by a pre-release part after a hyphen (1.1.0-rc.0) and build metadata after a plus sign (1.1.0+build.42, ignored when ordering). The v prefix is not part of SemVer, but npm 2,036 , Go modules and most hosts expect it on tags.
| Part | Bump it when | BookNest example |
|---|---|---|
| MAJOR | A change breaks existing clients | Renaming the inStock field |
| MINOR | You add a feature that breaks nothing | Adding GET /api/genres |
| PATCH | You fix a bug without changing the API | Correcting a sort order |
A pre-release sorts before its release. A genres endpoint is a new feature, so the next release is a MINOR one. npm version edits package.json and package-lock.json, commits, and creates an annotated tag:
# Edit app.js, test/api.test.js and README.md: add GET /api/genres
git commit -qam "Add GET /api/genres with a book count per genre"
npm version preminor --preid rc -m "Release %s"
npm version minor -m "Release %s"
git log --oneline --decorate -3v1.1.0-rc.0 v1.1.0 5f14f72 (HEAD -> main, tag: v1.1.0) Release 1.1.0 57d1998 (tag: v1.1.0-rc.0) Release 1.1.0-rc.0 d1f397c Add GET /api/genres with a book count per genre
preminor --preid rc went from 1.0.0 to 1.1.0-rc.0 for testers; once the candidate passed, minor promoted it to 1.1.0. %s becomes the version, and npm refuses to run in a dirty working tree, so unfinished edits never ship under a release number.