@crystal-ball/commit-semantics

🔮 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 with ctrl+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:

1. Analyze commits made since the last release to determine if a release should occur and what the version should be.
2. Parse commits to generate a set of formatted release notes.
3. Append release notes to the top of the project Changelog.
4. Push a release commit and tag to Github
5. Publish the release to NPM
6. Publish a Github release and add comments and labels to all issues and PRs included in the release.

🔋 Included packages

• commitizen
• @crystal-ball/commitizen-adapter
• semantic-release
• @crystal-ball/semantic-release-base
• @semantic-release/commit-analyzer
• @semantic-release/release-notes-generator
• @semantic-release/changelog
• @semantic-release/git
• @semantic-release/npm
• @semantic-release/github