🔮 Projects - Commit Semantics
Fully automated commit and release workflows with Commitizen and Semantic Release
This package is a batteries included manager for setting up standardized commit messages with Commitizen and automated CI/CD releases with Semantic Release.
- Standardized commit messages are constructed using an interactive prompt with options for long descriptions, emojis, breaking change notes and release notes.
- Fully automated releases include package version and changelog updates, npm publishing, and Github release comments and labels.
⚙️ Setup
1. Install
npm i -D @crystal-ball/commit-semantics husky
2. Configure package.json
{
"config": {
"commitizen": {
"path": "@crystal-ball/commitizen-adapter"
}
},
"husky": {
"hooks": {
"prepare-commit-msg": "exec < /dev/tty && git cz --hook"
}
},
"release": {
"extends": ["@crystal-ball/semantic-release-base"]
}
}
3. Configure .github/workflows/ci-cd.yml
# Release with Semantic after tests pass on master
jobs:
ci-cd:
runs-on: ubuntu-latest
steps:
- name: Release
if: success() && github.ref == 'refs/heads/master'
run: npx semantic-release
env:
GH_TOKEN: ${{ secrets.SEMANTIC_GH_TOKEN }}
NPM_TOKEN: ${{ secrets.SEMANTIC_NPM_TOKEN }}
This configuration will run semantic-release
on any change to the master
branch. Commit types of New
, Update
and Fix
, or any commit containing a
BREAKING CHANGES
footer will trigger a release.
4. Configure Secret
SEMANTIC_GH_TOKEN
and SEMANTIC_NPM_TOKEN
access tokens for npm and Github
should be added to the secrets in the repo settings.
🔖 Commit standards
Fully automated releases are only possible by following a standard commit message format that can be parsed when the release job is run. The ESLint format is used and must follow the pattern:
<tag>: <message>
The Husky prepare-commit-msg
hook will execute the Commitizen prompt on each
commit and using the prompts will ensure the commit is valid.
ℹ️ It is possible to skip the interactive prompts withctrl+c
as well as changing the commit after construction, but neither is recommended.
Configuration of the commitizen adapter is managed in the
@crystal-ball/commitizen-adapter
package.
🚀 Release tasks
On change to master Semantic Release is run and will manage:
- Analyze commits made since the last release to determine if a release should occur and what the version should be.
- Parse commits to generate a set of formatted release notes.
- Append release notes to the top of the project Changelog.
- Push a release commit and tag to Github
- Publish the release to NPM
- Publish a Github release and add comments and labels to all issues and PRs included in the release.