Release procedure

We are using Comitizen.

We are automating vi semantic versionning (SemVer) + CHANGELOG with Commitizen

Goal

With each release, a single command (cz bump --changelog) will automatically:

Analyze your commits (Conventional Commits)
Calculate the new version (patch, minor, major)
Update the version in your files
Generate/update the CHANGELOG.md - Create the release commit and Git tag

Installation

# Global installation or within your virtual environment
pip install commitizen

# Verify installation
cz version

Working with Conventional Commits

Creating standardized commits

Two methods:

Method 1: Interactive guide (recommended for beginners)

cz commit

An assistant guides you step by step: 1. Choose the change type (fix, feat, docs, etc.) 2. Enter the message 3. Describe the scope (optional) 4. Indicate breaking changes (if any)

Method 2: Manually

# Bug fix → patch (0.1.0 → 0.1.1)
git commit -m "fix: fix connection timeout"

# New feature → minor (0.1.0 → 0.2.0)
git commit -m "feat: add OAuth2 authentication"

# Breaking change → major (0.1.0 → 1.0.0)
git commit -m "feat: new REST API

BREAKING CHANGE: removed v1 endpoints"

Commit types and version impact

Commit type	Incrementation	Example
`fix:`	patch (+0.0.1)	`f ix: fix display bug`
`perf:`	patch (+0.0.1)	`per f: optimize queries`
`feat:`	minor (+0.1.0)	`f eat: add PDF export`
`BREAKING CHANGE:` (in message)	major (+1.0.0)	any type + `BREAKING CHANGE:`

The magic command - Creating a release

When you’re ready to publish a new version:

# Analyzes commits since last tag and executes the release
cz bump --changelog

What this command does exactly:

Analyzes all commits since the last Git tag
Calculates the next version (patch/minor/major)
Updates the version in all listed files
Generates/updates the CHANGELOG.md (adds the new entry at the top)
Automatically commits the changes with the message: "bump: version X.Y.Z"
Creates a Git tag (format vX.Y.Z)

Concrete execution example:

$ cz bump --changelog
INFO: Starting version bump from 1.0.0 to 1.1.0
INFO: Updating version in pyproject.toml
INFO: Updating version in src/my_project/__init__.py
INFO: Generating CHANGELOG.md
INFO: Created commit: bump: version 1.1.0
INFO: Created tag: v1.1.0

Managing the auto-generated CHANGELOG

The CHANGELOG.md file will look like this:

## v1.1.0 (2024-01-15)

### Feat

- add OAuth2 authentication
- add PDF export

### Fix

- fix connection timeout

## v1.0.0 (2024-01-10)

### Breaking Changes

- removed v1 endpoints

### Feat

- first version of REST API

You can customize the template by adding to pyproject.toml:

[tool.commitizen]
# ... existing configuration ...
changelog_template = "custom_changelog_template.j2"  # Custom Jinja2 template

Pushing the release to Git

After cz bump --changelog, you have a commit and a tag locally. Push them:

# Push the commit and tags
git push --follow-tags

Useful daily commands

Command	Purpose
`cz commit`	Interactive guide to create a conventional commit
`cz bump --changelog`	The main command: bumps version + CHANGELOG
`cz check`	Checks if your last commit follows the convention
`cz version`	Displays current version (according to Commitizen)
`cz changelog`	Generates only the CHANGELOG without bumping
`cz bump --prerelease alpha`	Creates a pre-release version (e.g., 1.0.0-alpha.1)

Summary: The ideal workflow in 3 steps

# 1. During development: standardized commits
git add .
cz commit                    # or git commit -m "feat: ..."

# 2. When you're ready for a release
cz bump --changelog

# 3. Push to Git
git push --follow-tags

And that’s it! Version bumped, CHANGELOG generated, tag created, all automated.