semantique

1.5.2 • Public • Published

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
npm version Build Status Prod Dependencies Dev Dependencies NPM Downloads Docker Pulls

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 Y
  • Breaks 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:

  1. Run npm install -g semantique
  2. Commit your changes to your projects.
  3. 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.

Contributing

Feature suggestions and improvements welcome. Early days.

Package Sidebar

Install

npm i semantique

Weekly Downloads

2

Version

1.5.2

License

MIT

Last publish

Collaborators

  • steve-gray