@priestine/semantics automates version bumping for your projects. It determines the next SemVer version number, generates the release notes, updates the CHANGELOG and publishes the release tag.

• Compatibility with Github, Gitlab and Bitbucket
• Automated versioning that follows SemVer
• Automatically generated release notes
• Simple and transparent way of releasing your code
• Support for formalized commits that follow widely adopted Conventional Commits specification
• Works with any programming loanguage
• Simple integration with any CI/CD tool
• Convenience Docker images for your entertainment

npm i -g @priestine/semantics

The easiest way to use the app is to go get the Docker image from Docker Cloud. You can create a separate job in your .gitlab-ci.yml that will bump your versions. In fact, it is as simple as:

# .gitab-ci.yml

stages:
  - versioning

versioning:
  stage: versioning
  image: priestine/semantics:latest
  script:
  - priestine-semantics --prefix=v
  only:
  - master

# .travis.yml

language: node_js
node_js:
  - "10"
stages:
  - name: versioning
    if: branch = master
jobs:
  include:
    - stage: versioning
      script:
        - npm install -g @priestine/semantics
        - priestine-semantics --user=$CI_USER --password=$CI_PASSWORD --prefix=v

priestine/semantics:latest Docker image is built from node:10-alpine.

There are also priestine/semantics@alpine version which is equal to priestine/semantics:latest as well as priestine/semantics:slim with the same contents yet based on node:10-slim.

Docker images are built on each priestine/semantics release so you can stick to the version you are comfortable with, e.g. priestine/semantics:2.8.0-alpine or priestine/semantics:2.8.0-slim.

If you want to run @priestine/semantics yourself locally (or elsewhere except for CI) you will need Node.js 8 or higher installed on your machine. Simply install the package globally. Then, in your project directory, run:

priestine-semantics

You can customize the behaviour of priestine-semantics command by providing command line options. All CL options resemble ConfigInterface properties written as kebab-case keys with double hyphen (--) before the key and equals sign (=) between the key and the value (=<value> is optional and converts to =true if it wasn't provided). To provide CL options, simply provide them after the command itself, e.g.:

priestine-semantics --prefix=v --precise-version-matching

Alternatively, you can use environment variables. All env variables exposed by @priestine/semantics resemble ConfigInterface properties written as UPPER_SNAKE_CASE keys with an equals sign (=) between the key and the value. Unlike CL options, environment variables MUST have a value.

PREFIX=v priestine-semantics

• --user=<username> - existing user that has access to the repository.
• --password=<value> - user password or access token for publishing tags.
• --git-user-name=<value> - name of a git user who will be associated with the release.
• --git-user-email=<value> - email of a git user who will be associated with the release.
• --publish-tag[=<true|false>] - if true, @priestine/semantics will attempt to publish release tag to the platform. Defaults to true.
• --oldest-commits-first[=<true|false>] - if true, commits in the release notes will be sorted chronologically, oldest to latest. Defaults to true.
• --tag-message[=<true|false>] - if true, tag release notes will be generated and added as release message when publishing. Defaults to true.
• --prefix=<value> - set prefix for newly created version (e.g. --prefix=v -> v1.0.0).
• --postfix=<value> - set postfix for newly created version (e.g. --postfix=-beta -> 1.0.0-beta).
• --write-to-changelog[=<true|false>] - if true, tag release notes will be prepended to ./CHANGELOG.md. Defaults to true.
• --origin=<value> - custom remote origin to push release tag to. If not specified, updates are pushed to the current repository.
• --write-temporary-files[=<true|false>] - if true, @priestine/semantics will create temporary files containing the data gathered during its execution (NOTE: temporary files are not generated if there are no reasons for version bumping)
• --precise-version-matching[=<true|false>] - if true, @priestine/semantics will look for previous versions with given prefix and/or postfix instead of just looking for any previous SemVer-like tag. This is helpful for leading several changelogs for various types of releases.
• --exclude-merges[=<true|false>] - if true, merge request commits will be excluded when evaluating changes since latest version. Defaults to true.

• USER=<username> - existing user that will be associated with the release.
• PASSWORD=<value> - user password or access token for publishing tags.
• GIT_USER_NAME=<value> - name of a git user who will be associated with the release.
• GIT_USER_EMAIL=<value> - email of a git user who will be associated with the release.
• PROJECT_PATH=<value> - project path for building the URL in chosen platform for publishing the release tag. E.g. priestine/semantics stored on Github will mean publishing to https://api.github.com/repos/priestine/semantics/releases.
• PUBLISH_TAG=<true|false> - if true, @priestine/semantics will attempt to publish release tag to the platform. Defaults to true.
• OLDEST_COMMITS_FIRST=<true|false> - if true, commits in the release notes will be sorted chronologically, oldest to latest. Defaults to true.
• TAG_MESSAGE=<true|false> - if true, tag release notes will be generated and added as release message when publishing. Defaults to true.
• PREFIX=<value> - set prefix for newly created version (e.g. PREFIX=v -> v1.0.0).
• POSTFIX=<value> - set postfix for newly created version (e.g. POSTFIX=-beta -> 1.0.0-beta).
• WRITE_TO_CHANGELOG=<true|false> - if true, tag release notes will be prepended to ./CHANGELOG.md. Defaults to true.
• ORIGIN=<value> - custom remote origin to push release tag to. If not specified, updates are pushed to the current repository.
• WRITE_TEMPORARY_FILES=<true|false> - if true, @priestine/semantics will create temporary files containing the data gathered during its execution (NOTE: temporary files are not generated if there are no reasons for version bumping)
• PRECISE_VERSION_MATCHING=<true|false> - if true, @priestine/semantics will look for previous versions with given prefix and/or postfix instead of just looking for any previous SemVer-like tag. This is helpful for leading several changelogs for various types of releases.
• EXCLUDE_MERGES=<true|false> - if true, merge request commits will be excluded when evaluating changes since latest version. Defaults to true.

While running, @priestine/semantics generates a few temporary files for your disposal.

Temporary file output will only be created if a new release is required.

The commit assigned to the previous tag (if there was previous release tag in place for current project).

4ed93c713f65eff843406a549c740132c99da123

Previous tag (if there was previous release tag in place for current project).

2.2.3

The version that should be assigned according to the contents of the commits.

2.2.4

JSON containing all the commits that were evaluated.

[
  {
    "hash": "4ed93c713f65eff843406a549c740132c99da123",
    "abbrevHash": "4ed93c7",
    "author": {
      "name": "priestine1",
      "email": "[email protected]"
    },
    "subject": "Correct writing of normalized changes to JSON",
    "body": [],
    "issueReference": "#25",
    "type": "fix",
    "breakingChanges": []
  },
  {
    "hash": "36af8aaa38cea6613c773ce55390a09d7e5898d0",
    "abbrevHash": "36af8aa",
    "author": {
      "name": "priestine1",
      "email": "[email protected]"
    },
    "subject": "Last attempt to fix publishing for today",
    "body": [],
    "issueReference": "#14",
    "type": "fix",
    "breakingChanges": []
  }
]

Markdown changelog for evaluated commits.

# 2.2.4


## Bug Fixes

`A bug fix`

* **4ed93c7**: Correct writing of normalized changes to JSON (**#25**)
* **36af8aa**: Last attempt to fix publishing for today (**#14**)

Let people know that your package is published using @priestine/semantics by including the badge in your README:

[![versioning: semantics](https://img.shields.io/badge/versioning-semantics-912e5c.svg)](https://github.com/priestine/semantics)