@cley_faye/version-manager

Manage updating version number in an NPM project.

Installation

npm install -g @cley_faye/version-manager`

Usage

verman-bump <bump type>

Additionally, you can call the command with --help to get more informations.

Workflow

Versions

The version handling is expected to go this way:

• It follows semantic versioning:
  • a patch version only fix things and must remain 100% compatible with previous version as far as API/ABI is concerned.
  • a minor version can add features as long as the API/ABI remain compatible with previous versions (either by not changing them or by setting identical default versions as before).
  • a major version will break compatibility; someone updating to a newer major version is expected to potentially have some changes to do in their codebase.
• Additionally, dev versions are created in-between.

Basically, every time a version is "settled", the package is immediately put in a new dev.0 version. Incremental dev version are tagged on odd numbers; dev.0 is not usually tagged, then dev.1 would be, leading into dev.2 not being tagged, etc.

Changelog

A changelog file can be created, and updated, on each actual releases. Add --changelog to the verman-bump command to create it. If a changelog file is detected, it will be automatically updated on subsequent calls.

Operations

When making an actual version (not a dev one), the following steps are followed:

• Ensure that the git repository is clean
• Calls script verman_precommit.sh if present
• Create the version commit message
• Update/create the changelog
• Ask for user confirmation
• Update package.json/lockfile
• Commit
• Tag
• Commit dev-version
• Calls script verman_prepush.sh if present
• Push
• Calls script verman_postpush.sh if present

Note that this does not use scripts from package.json like preversion, version, and postversion. The actual sequence of operation is slightly different here, and it would be more annoying than useful to plug into these.

Commit message

When making a new versions, all short commit titles since the previous version are provided as the baseline for the commit message. In addition, a set of lines will be added (like Breaking:, Added:, etc.). In the commit message it is advised to keep the structure of headings ending with a :, and lines in each section to be prefixed with - (as suggested). This will help the creation of the changelog file. The commit message format retain the expected git format, as in, the first line is the short description, following by a blank line, then the commit message.

Hooks

The hooks are called during operations:

verman_precommit.sh

This is called before the actual commit. It will have the following environment variables set:

• bumpType: type of version bump
• previousVersion: the version before the change
• nextVersion: the version after the change
• message: the version commit message

This script can explicitly add file to the version commit, but this should be limited to actual version changes, nothing else.

verman_prepush.sh

Called before actually pushing on the git remote. It will have the following environment variables set:

• bumpType: type of version bump
• previousVersion: the version before the change
• nextVersion: the version after the change

verman_postpush.sh

Called after pushing on the git remote. It will have the following environment variables set:

• bumpType: type of version bump
• previousVersion: the version before the change
• nextVersion: the version after the change

verman_postcancel.sh

Called when the user cancel the version update. At this point, all changes made by the script are reverted, but changes made by hooks are not automatically cleaned.