ngx-semantic-version

ngx-semantic-version is an Angular Schematic that will add and configure commitlint, commitizen, husky and standard-version for creating commit messages in the conventional commit format and automate your release and Changelog generation respecting semver.

The schematic will configure the following packages / services:

• commitlint
• husky
• commitizen
• standard-version

How to use

Add the schematics to your project

• Angular CLI >= 9.x.x

  ng add ngx-semantic-version

• Angular CLI 8.x.x | docs

  ng add ngx-semantic-version@1

if you have already configured one of the modules and you want to use the configuration provided by ngx-semantic-version, you can use --overrideConfigurations to override an existing configuration. Please check the changes carefully using git after running with --overrideConfigurations.

available options

Flag	Description
--skipInstall	Skips installing new node_modules after modifying package.json
--packages="commitlint, husky, commitizen, standard-version"	Define the packages to add.
--issuePrefix="<PREFIX>"	Configure an issue prefix that should be checked by each commit
--overrideConfigurations	Do override existing configuration parameters if necesary
--force	Ignore errors and override already existing files
--standardVersionConfig	Add the base configuration for standard-version to package.json for adjusting it later

force including references by configuring an issue prefix

When adding the schematic using e.g. --issuePrefix="PREFIX-", commitlint will be configured to use the defined issue prefix in commit messages. Therefore the following configuration will be added to the commitlint.config.js configuration file:

module.exports = {
  // ...
  rules: {
    'references-empty': [2, 'never'],
  },
  parserPreset: {
    parserOpts: {
      issuePrefixes: ['PREFIX-'],
    },
  },
};

This is very helpful if you want to force the users to include always an reference to your issue tracking system (in the example above the issue racking system will use this style: PREFIX-1242).

The line 'references-empty': [2, 'never'], will tell commitlint that an issue reference has to be included always. You can change the value of 2 to 1 to just warn the user instead of rejecting the commit messages. All configuration option are described in the official docs of commitlint.

The prefix will be also configured for usage within standard-version in your package.json:

// ...
"standard-version": {
  "issuePrefixes": ["PREFIX-"],
}

You can specify further options for standard-version that will be uses for the generated links in CHANGELOG.md generation. You can adjust the configuration block standard-version in your package.json and adjusts the options to satisfy your needs.

Update the schematics

Run ng update to see if an update is available. To proceed running an update of ngx-semantic-version, run the following command:

ng update ngx-semantic-version

Updates will may touch your existing configuration. Please check the changes using git to verify the changes.

What's included

commitlint

Commitlint will lint your commit message and check it against some common rules. It will throw an error if the messages doesn't match with the rules. This schematic will install the ruleset @commitlint/config-conventional by default.

After adding the schematics you will be able to adjust the rules for your personal needs by adjusting the added file commitlint.config.js.

You can find a description of supported adjustments in the official documentation.

husky

Husky allows us to hook into the git lifecycle using nodejs. It is used by ngx-semantic-version to check a commit message right before storing it by using commitlint. Therefore it will add this part to your package.json:

...
"husky": {
  "hooks": {
    "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
  }
},

Husky uses the environment variable HUSKY_GIT_PARAMS containing the current git message you entered and it will pass this through commitlint so it can be evaluated.

commitizen

When having restrictions within the commit message text it can be difficult to always satisfy the appropriate format. Commitizen will help you to build a commit message always in the appropriate format by letting you configure the final message via an interactive cli.

When commitizen is installed globally (npm i -g commitizen) you can run it by executing git cz.

Alternatively, if you are using NPM 5.2+ you can use npx instead of installing globally: npx git-cz.

ngx-semantic-version will configure commitizen in your package.json, so that is will use the conventional changelog as well:

...
"config": {
  "commitizen": {
    "path": "./node_modules/cz-conventional-changelog"
  }
}

Tip: if you are using vscode, you can add the plugin Visual Studio Code Commitizen Support which will let you build the commit message directly via vscode.

standard-version

Standard-version will create and update your app/package version and automatically generate a CHANGELOG.md file and keep it up-to-date by using the git history. It will check the messages for keywords (thanks to commitlint) and determine which part of the semantic version will be increased. Furthermore it will add a tag for the version.

After adding this schematic, you can simply release a new version by running npm run release. This will keep your CHNAGELOG.md up to date and releases a new version of your project.

ngx-semantic-version will configure a new script in your package.json that can be used for releasing a new version:

...
"scripts": {
  "release": "standard-version",
},

If you typically use npm version to cut a new release, do this instead:

npm run release

You should also consider use one of the following commands:

npm run release -- --first-release    # create the initial release and create the `CHANGELOG.md`
npm run release -- --prerelease       # create a pre-release instead of a regular one
npm run release -- --prerelease alpha # cut a new alpha release version

To adjust the temnplate of the generated CHANGELOG.md or the types of commits included in it you need to modify the standard-version configuration. You can use --standardVersionConfig within ngx-semantic-version to add the default configuration to your package.json. After that you can simply adjust the configuration to your needs:

ng add ngx-semantic-version --standardVersionConfig

Please note that your projects repository field should be filled in your package.json, as standard-version will use this information for creating the links in the CHANGELOG.md to your issues and releases. Check out also the official documentation for further information.

Default configurations

Check out the file src/ng-add/defaults.ts if you want to see what part will be added to your package.json and see the default values.

Development

For development hints, have a look at DEVELOPMENT.md