智慧物流>> semantics>> 返回
项目作者： orlovedev

项目描述 ：
Automatic version bumping tailored for your wants and needs.
高级语言： TypeScript
项目地址: git://github.com/orlovedev/semantics.git
创建时间： 2019-04-01T23:11:38Z
项目社区：https://github.com/orlovedev/semantics
开源协议：MIT License
下载


@priestine/semantics

Build Status codecov @priestine/semantics"">npm @priestine/semantics"">npm

licence: MIT code style: prettier versioning: 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

  1. 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:

  1. # .gitab-ci.yml
  3. stages:
  4.   - versioning
  6. versioning:
  7.   stage: versioning
  8.   image: priestine/semantics:latest
  9.   script:
  10.   - priestine-semantics --prefix=v
  11.   only:
  12.   - master

Travis CI

  1. # .travis.yml
  3. language: node_js
  4. node_js:
  5.   - "10"
  6. stages:
  7.   - name: versioning
  8.     if: branch = master
  9. jobs:
  10.   include:
  11.     - stage: versioning
  12.       script:
  13.         - npm install -g @priestine/semantics
  14.         - priestine-semantics --user=$CI_USER --password=$CI_PASSWORD --prefix=v

Docker image info

Docker Pulls Docker Stars MicroBadger Layers MicroBadger Size

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:

  1. 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.:

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

  1. 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).

  1. 4ed93c713f65eff843406a549c740132c99da123
.tmp.current_tag_data (Example)

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

  1. 2.2.3
.tmp.version_data (Example)

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

  1. 2.2.4
.tmp.current_changes.json (Example)

JSON containing all the commits that were evaluated.

  1. [
  2.   {
  3.     "hash": "4ed93c713f65eff843406a549c740132c99da123",
  4.     "abbrevHash": "4ed93c7",
  5.     "author": {
  6.       "name": "priestine1",
  7.       "email": "priestine1.dev@gmail.com"
  8.     },
  9.     "subject": "Correct writing of normalized changes to JSON",
  10.     "body": [],
  11.     "issueReference": "#25",
  12.     "type": "fix",
  13.     "breakingChanges": []
  14.   },
  15.   {
  16.     "hash": "36af8aaa38cea6613c773ce55390a09d7e5898d0",
  17.     "abbrevHash": "36af8aa",
  18.     "author": {
  19.       "name": "priestine1",
  20.       "email": "priestine1.dev@gmail.com"
  21.     },
  22.     "subject": "Last attempt to fix publishing for today",
  23.     "body": [],
  24.     "issueReference": "#14",
  25.     "type": "fix",
  26.     "breakingChanges": []
  27.   }
  28. ]

.tmp.changelog.md (Example)

Markdown changelog for evaluated commits.

  1. # 2.2.4
  4. ## Bug Fixes
  6. `A bug fix`
  8. * **4ed93c7**: Correct writing of normalized changes to JSON (**#25**)
  9. * **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:

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