@priestine/semantics

@priestine/semantics

@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.

Features

• 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

Installation

npm i -g @priestine/semantics

GitLab CI using Docker image

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 CI

# .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

Docker image info

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.

Manual usage

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

Customizing behaviour

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

Command Line Options

• --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.

Environment Variables

• 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.

Temporary files

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.

Temporary file description

.tmp.current_commit_data (Example)

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

4ed93c713f65eff843406a549c740132c99da123

.tmp.current_tag_data (Example)

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

2.2.3

.tmp.version_data (Example)

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

2.2.4

.tmp.current_changes.json (Example)

JSON containing all the commits that were evaluated.

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

.tmp.changelog.md (Example)

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**)

Supported Versions

Version	Supported
5.1.x	:white_check_mark:
5.0.x	:x:
4.0.x	:white_check_mark:
< 4.0	:x:

Badge

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)