Pver NPM | npm.io

`pver` - A CLI for releasing pragmatic versions

pver is a cli tool for releasing Pragmatic Versions. You can use pver as a simpler alternative to semantic-release for npm repositories. Alternatively if you already use semantic-release, you can use a pragmatic versioning release config

Pragmatic versioning optimizes for communicating changes to a package to package consumers, while retaining simple semantics for package maintainers.

Given a version number BIGRELEASE.ANNOUNCE.INCREMENT, increment the:

BIGRELEASE version whenever a major milestone, periodic version cut (e.g. a yearly release) or other marketed version change occurs, a BIGRELEASE is often accompanied with a maintanence period.
ANNOUNCE version whenever you have made an substantial incompatible API change, introduced a new set of features, or any change that an end user using the software normally may notice and should accompany an announcement.
INCREMENT version for any new project contribution.

Installation

npm install -g pver

Then put this in a github workflow:

name: Publish to npm
on:
  push:
    branches:
      - main
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org/
      - run: npm install -g pver
      - run: npm ci
      - run: pver release
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Usage

# Automatically compute the latest Pragmatic Version using the
# git history
pver analyze
pver analyze --current-method=package.json --transition-method=simple

# Automatically compute the latest Pragmatic Version using the
# git history and release a new version as a git tag (and push it)
pver release --git

# Automatically compute the latest Pragmatic Version using the
# git history and increment the version in the package.json file, and
# the README.(md|txt) file
pver release --git --npm --readme

# Also available: --pyproject, --setuppy, --versionpy, --versionrb,
#                 --mdfile somefile.md

# Explicitly release a version
pver release increment --git
pver release announce --git
pver release bigrelease --git

# Automatically compute the latest Pragmatic Version using the
# git history, tag the current commit and stage the changes locally
pver stage --git
pver stage increment --git --npm

# Setup a Github repository to automatically release with pragmatic versions
pver setup github

Usage in Github Actions

Drop this into .github/workflows/publish.yml

name: Publish to npm
on:
  push:
    branches:
      - main
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-node@v3
      with:
        node-version: 20
        registry-url: https://registry.npmjs.org/
    - run: npm install -g pver
    - run: npm ci
    - run: pver release
      env:
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Analysis

Analysis has two steps. Getting the current_version and using the transition_method to determine the next version. You can manually specify both the state method and the transition method.

Usually, the current_version is automatically determined by trying any available methods.

Current Version Methods (`--current-method`)

`package.json`

Use the version inside the package.json file.

`readme`

Parse two sections of README.txt or README.md for a version number in the format vX.Y.Z. Here's an example of a README.md with a version number:

# My Package v0.1.1

This is a description of my package!

Transition Methods (`--transition-method`)

`pver` Simple Commit Message Standard `simplegit`

By default, pver uses parses git commit history and looks for the following patterns:

bigrelease: <message> - A BIGRELEASE, increments the major/first version number
announce: <message> - A ANNOUNCE release, increments the minor/second version number
Anything else - An INCREMENT release, increments the patch/third version number

pver then uses the largest version bump to determine the next version. It will only increment a version number by a maximum of 1 per run. This means that intermediate commits are not released.