Semantique NPM

semantique

Semver, the old fashioned way

Semantic versioning based purely on current Git workspace without dependencies on package registries or CI systems (though you can integrate one if you want).

Current Version	Latest Build	Dependencies	Dev Dependencies	NPM	Docker

How It Works

The semantique package checks the current working directory to determine any changes that have been made since the last tag on the branch. Commits use semver like directives to indicate the nature of the change.

The following prefixes are recognised by default:

Prefixes	Semver Meaning	Notes	Examples
break	Major	When a breaking change has occured.	break(module): No longer default X to YBreaks all of the stuff.
feat	Minor	A new feature or widening change to an operational contract/API.	feat(something): Added widget frobber.Feature: Something else.
patch / bugfix / fix	Patch	A fix to correct a deviation from specified behaviours.	fix(something): Shouldn't do that.PATCH: Urgently prevent disaster.

Any other commits that are not prefixed with the above are assumed to be non-consequential and not trigger a new version.

In short:

Run npm install -g semantique
Commit your changes to your projects.
Run semantique

The package will then read the commits and tags, determine the next tag (defaulting to 1.0.0 for the first hit)

Example Projects

I've switched many of my own packages to use semantique, such as my IOC module, somersault. The .drone.yml for that project represents what I'd consider best practices for using this module.

Running with CI Systems (Drone, GoCD)

To run with a CI system, I publish a convienient docker image. This image can be used with your pipeline such as:

    pipeline:
       install_npm_packages:
            image: node:4
            commands:
                - npm install
                - npm test

        run_semantique_self:
            image: eventualconsistency/semantique
            pull: true
            when:
                branch: master
                event: push

It is assumed that the upstream origin URL is already set on your git workspace for the purposes of publishing. You need to set the following environment variables (as secrets in Drone/GoCD):

Environment Variable	Used For
GIT_USER	Username for publishing changes back to the upstream Git repository.
GIT_PASS	Password or personal access token (recommended) for publishing changes back to upstream.

The following environment variables are used to configure other aspects of the behaviour of semantique:

Environment Variable	Default	Notes
SQ_CMD_FETCH	git fetch --tags	The command to fetch the tags for the current repo. Runs before processing.
SQ_CMD_LOGS	git log --date=iso --pretty=format:\"%H \|\|\| %an \|\|\| %s \|\|\| %d\"	Command to extract the logs from SCM for parsing.
SQ_CMD_LOGDELIMITER	\|\|\|	Log delimiter for output.
SQ_CMD_LINEEND	\n	Line ending for parsing output
SQ_CMD_WORKSPACEPENDING	git diff --name-only	Command for checking if the workspace is clean.
SQ_CMD_PUSH	git push origin master --tags	Command for pushing back to upstream branch.
SQ_COMMIT_MESSAGE	Updated to version %s for release.	Default message for commits
SQ_DEFAULT_VERSION	1.0.0	Initial version when no previous tags found on repo.
SQ_OPT_CHECKCLEAN	true	Check if the workspace is clean. Set to 0/false to allow dirty workspaces.
SQ_OPT_APPLYVERSION	true	Apply the versioning command to the package type. Set to 0/false to skip the version bump command
SQ_OPT_PUSH	true	Push to upstream repository after success?

Security and other Considerations

Be sure to:

Configure the GIT_USER / GIT_PASS secrets only for push operations for the semantique image.
Make sure semantique only runs on the main release branch for your project (branch: master in Drone or similiar), otherwise commits to other branches will trigger competing releases.
Due to the lack of a conditional publish operation in Drone, I typically configure the pipelines in my examples such that pushing the tag back is what triggers the actual NPM release on a second build run.
If you're using this in anger I'd recommend specifying a particular version of the image for Docker - rather than defaulting to latest. I'll never rewrite a version tag, but latest/smoke/onbuild will be subject to dramatic breaking changes.