Commitizen configuration that follows the Conventional Changelog format with emoji support

Table of Contents

• Overview
• Requirements
  • Developer Requirements
• Preview
• Format
• Installation
  • Installing Globally
  • Installing Locally
• Usage
• Contributing
• License

Overview

This project is a shareable Commitizen configuration. It is designed to work alongside git workflows that implement the Conventional Changelog format, Conventional Commits, and adds support for emojis (important for UX). This project borrows heavily from cz-conventional-emoji. It modifies it to include more aethestically pleasing emojis as well as to work seamlessly with the other configurations it is meant to work alongside, namely:

• semantic-release-config - An all-in-one Semantic Release plugin that supports NPM, Go, Python, and Docker projects (among a few others)
• conventional-changelog-emoji-config - Configuration for generating CHANGELOG.md files that look good on both GitHub and GitLab as well as accomodate situations where the GitHub/GitLab repository are mirrored

Requirements

If you are simply including this library in your project, all you need is a recent version of Node.js. Node.js >14.18.0 is sometimes required and is the only version range we actively support. Albeit, it is highly probable that lower versions will work as well depending on the requirements that this project imports.

Developer Requirements

The following versions of Node.js and Python are required for development:

• Node.js >14.18.0
• Python >3.10.0

Other versions may work, but only the above versions are supported. Most development dependencies are installed automatically by our Taskfile.yml set-up (even Node.js and Python). Run bash start.sh to install Bodega (an improved fork of go-task) and run the initialization sequence. The taskfiles will automatically install dependencies as they are needed, based on what development tasks you are running. For more information, check out the CONTRIBUTING.md or simply run:

npm run help

npm run help will ensure Bodega is installed and then open an interactive dialog where you can explore and learn about various developer commands.

Preview

After you set this configuration up, when you do git commit you will be prompted with an interactive menu. It will prompt you for the type of commit, ask for a subject, and a few other options. The whole process guides your commits and your repository's users commits to come out consistently in such a way that you can generate automated CHANGELOG.md files. semantic-release-config and conventional-changelog-emoji-config rely on this Commitizen configuration to generate commit messages that are in a consistent format.

Some of your commit message titles may look something like:

- ✨ feat: add signup pages from (#11)
- 🐛 fix(test): get browser width for android devices
- ♻️ refactor(sc): refactor to styled component
- 🧪 test: add test for splitmerge

Format

Format of the commit is below:

[emoji] [type]([scope]): [commit msg] (#[issue number])

Note: scope & issue number are optional.

Installation

First, ensure Commitizen (a.k.a. git-cz) is installed. Then, add this package to your system either globally or locally.

Installing Globally

You can install this library globally and have it run on all projects using the following method. First, install the package globally:

npm install --global cz-conventional-emoji

After that, configure Commitizen to use the library by default:

echo '{ "path": "cz-conventional-emoji" }' > ~/.czrc

Installing Locally

To install the library locally (so that the configuration is portable with your repository), add it to your devDependencies by running:

npm i -D cz-conventional-emoji

With the library installed locally, you next have to configure package.json to point to the configuration by adding a section that should look something like this:

{
  "name": "my_node_module_name",
  ...
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-emoji"
    },
  },
  ...
}

Usage

Simply use git cz instead of git commit when committing. See the documentation of Commitizen for more information.

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page. If you would like to contribute, please take a look at the contributing guide.

Brian Zalewski

License

Copyright © 2020-2021 Megabyte LLC. This project is MIT licensed.