@werkzeugkiste/release-config

This is the shared semantic-release config for all things @werkzeugkiste related. It includes a semantic-release config for libraries and a commitlint config that works well together with the semantic-release config. It also has semantic-release and commitlint as direct dependencies so it does not need to be installed separately.

With this semantic-release config you get the following features out of the box:

• version number detection for releases based on commit messsages
• version number is written back to package.json
• publishing of new release versions to npm
• creation of tags incl. release notes on GitHub for every new release
• generation of a CHANGELOG.md file containing all changes since last release
• rejection of commits that are not according to the commit message convention (optional)

The semantic-release and commitlint configs are basically based on the Angular config/preset but extended with some additional features and custom commit types.

Installation

# installation using yarn
yarn add --dev @werkzeugkiste/release-config

# installation using npm
npm install --develop @werkzeugkiste/release-config

Usage

If you want to use this config as base in any of your projects, you need to create a relase.config.js file in your project folder that re-exports the semantic-release config from @werkzeugkiste/relase-config.

You can do that by creating a file named release.config.js in your project's root folder with the following content:

module.exports = require('@werkzeugkiste/release-config/release.config');

Optionally, you can also use the corresponding commitlint config so that commits are only allowed if they are valid semantic-release style commits. That means they must have a commit message starting with a type (e.g. fix:, feat:, chore:, ...) followed by an optional scope (e.g. fix(core):, feat(api), ...) and a subject (i.e. the actual commit header). Types and scopes are case sensitive and must be all lowercase. Your commit may contain additional description in the commit message body. Have a look at the Angular Commit Message Guidelines for more info. You can find the full commit type/release rules config in release.config.js.

In order to use the commitlint config (and I'd strongly recommend you to do so!) create a file named .commitlintrc.js in your project's root folder with the following content:

module.exports = require('@werkzeugkiste/release-config/.commitlintrc');

Afterwards you need to install and configure husky so that git hooks are run whenever something git related happens. Your .huskyrc should be updated to look like this:

{
  "hooks": {
    "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    // your other hooks:
    // [...]
  }
}

CI/CD integration

semantic-release only makes sense if you integrate it into your CD/CI process. Check out the official docs on CI configuration and the CI recipes to learn more about how you can use it with the CI tool of your choice.

Since this config is using the GitHub and npm plugins, you must set a GH_TOKEN and an NPM_TOKEN environment variable in your CI environment as described on the docs page.

Known issues

• ~~It seems like as if the custom commit types aren't respected by @semantic-release/release-notes-generator. This should be investigated. This Stack Overflow issue might be helpful.~~

  solved: the angular preset for release-notes-generator does not allow to assign custom types to specific sections.

• ~~when BREAKING CHANGE: is used in the footer to trigger a new major release, the subject in the header is not included in the release notes. I don't know if this is intentional but it feels wrong to me.~~

More info

• conventional-changelog-conventionalcommits is used as preset for release-notes-generator because it allows us to assign our custom commit types to sections (headlines) in the generated release notes and changelog. The angular preset for example does not provide such a feature.

• v8.3.3+ of @commitlint/cli and @commitlint/config-conventional is required for the breaking change shorthand syntax (<type>!:) to be parsed and recognized properly (related comment).

• This config only triggers new releases from master branch. When you're working on branches there are a few important things you should know:

  • if you use the Squash and merge function on GitHub, all previous commit messages are ignored by semantic-release! Only the final merge commit will be used. You should not do that unless it's absolutely necessary. Use the Pull Request title in a semantic-release way (i.e. prefix it with the commit type (fix, feat, etc.)) to tell semantic-release whether you want to release a major, minor or patch version. You can read more about that here.

  • if you use the Rebase and merge or Create a merge commit function everything works "as expected": all your commits will be analyzed once they're merged into master and semantic-release will do its job correctly.

    Here's a little illustration: