Commitizen Conventional Commit Guide

This guide explains how to use commitizen with NEMDataTools to follow the Conventional Commits specification.

What is Commitizen?

Commitizen is a tool that helps you write standardized commit messages according to the Conventional Commits format. When used with pre-commit, it ensures all commit messages follow the same format.

Commit Message Format

type(optional scope): description

[optional body]

[optional footer(s)]

Types

The type must be one of the following:

  • feat: A new feature

  • fix: A bug fix

  • docs: Documentation changes

  • style: Code style changes (whitespace, formatting, etc.)

  • refactor: Code changes that neither fix bugs nor add features

  • perf: Performance improvements

  • test: Adding or fixing tests

  • build: Changes to the build system or dependencies

  • ci: Changes to CI configuration files and scripts

  • chore: Other changes that don’t modify src or test files

Scope

The scope is optional and should be a noun describing the section of the codebase affected:

  • downloader

  • cache

  • processor

  • timeutils

  • tests

  • docs

Description

The description is a short summary of the code changes. It should:

  • Use imperative, present tense (e.g., β€œchange” not β€œchanged” or β€œchanges”)

  • Not capitalize the first letter

  • Not end with a period

Examples

feat(downloader): add retry mechanism for HTTP requests

fix(cache): resolve file permission issue when creating cache directory

docs: update installation instructions with UV commands

refactor(processor): simplify data standardization function

Creating Commits with Commitizen

Interactive Mode

Use commitizen in interactive mode:

cz commit

This will guide you through creating a valid commit message by asking for:

  1. The type of change

  2. The scope (optional)

  3. A short description

  4. A longer description (optional)

  5. Breaking changes (optional)

  6. Issues closed (optional)

Conventional git commit

You can also write commits directly using the conventional format:

git commit -m "feat(downloader): add support for P5MIN data type"

Pre-commit will validate if the message conforms to the conventional format.

Breaking Changes

For breaking changes, add a ! after the type/scope and include a BREAKING CHANGE: footer:

feat(api)!: remove deprecated endpoints

BREAKING CHANGE: The following endpoints have been removed as they were deprecated in v0.5.0

Referencing Issues

Reference issues at the end of the commit message:

fix(processor): handle missing values in CSV data

Closes #123

Benefits of Using Commitizen

  1. Standardized history: Makes the project history readable and structured

  2. Automated versioning: Can be used to automatically determine version numbers

  3. Automated changelog: Simplifies generating changelogs from commit messages

  4. Clarity: Clearly communicates the intent of changes

Commitizen CLI Commands

# Create a commit interactively
cz commit

# Check if the last commit message follows the convention
cz check --rev-range HEAD

# Bump version based on commits (when ready for release)
cz bump

Integration with NEMDataTools

Commitizen is integrated with NEMDataTools through:

  1. pre-commit hook: Validates commit messages automatically

  2. pyproject.toml: Configuration for commitizen

  3. Development workflow: Used throughout the project development

Customizing Commitizen

You can customize commitizen by adding a configuration to your pyproject.toml:

[tool.commitizen]
name = "cz_conventional_commits"
version = "0.1.0"
tag_format = "v$version"

This ensures everyone on the project follows the same commit conventions.