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:

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.