commitizen-tools/commitizen 3.0.0

on GitHub

What's new?

Let me start by thanking all the contributors 🎉 🙏🏻 , who landed most of the features I'm showcasing in this release 🚀 .

Does this breaking change affect me?

Only if you are using a cz plugin (like cz-emoji). You'll have to ask the maintainer to update to the new plugin system.

Or if you were using python 3.6 which is no longer supported.

Otherwise you are safe to upgrade

New plugin system

This is the main breaking change.

This change is relevant for maintainers of cz plugins.

Plugins are now exposed as commitizen.plugin entrypoints.
We no longer look at the package name and then for a discover_this. Instead you'll have to register the entrypoint.

If you are using poetry, add to pyproject.toml:

[tool.poetry.plugins."commitizen.plugin"]
cz_emoji = "cz_emoji:CzEmoji"

If you are using setup.py you'll have to use:

from setuptools import setup

setup(
    ...
    entry_points = {
        'commitizen.plugin': [
            'plugin = cz_emoji:CzEmoji'
        ]
    }
    ...
)

Read about migrating-from-legacy-plugin-format

Version providers

This amazing new feature will let you consume the version from what we call a "version provider", which is your project's version real source of truth. For example, a package.json, or your Cargo.toml.

Where before we had to modify the version in version_files:

[tool.commitizen]
version = "2.42.1"
tag_format = "v$version"
version_files = [
  "pyproject.toml:version",
  "commitizen/__version__.py",
  ".pre-commit-config.yaml:rev:.+Commitizen"
]

Now you can tell commitizen from where to read the version:

[tool.commitizen]
version_provider = "poetry"
tag_format = "v$version"
version_files = [
  "commitizen/__version__.py",
  ".pre-commit-config.yaml:rev:.+Commitizen"
]

You can see the source of truth for the version no longer belongs to the commitizen config.

With the new plugin system, you can write your own "version providers", and register them under the entrypoint commitizen.provider.

Read about version-providers

Version types

With the release of v3 we finally support semver. This is specially helpful when you are dealing with software that fully embraces semver, like Rust or Helm.

Previously, pep440 was the only one supported (still the default). Which behaves the same as semver, except when working with pre-releases.

If you are using python, we recommend sticking to pep440, but for any other kind of project, move to semver

Usage:

[tool.commitizen]
version_type = "semver"

Read more in version-types

Merge Pre-releases

You can merge all the pre-releases as part of the next non-pre-release in the changelog.

Read about merge-prerelease

Add the setting to commitizen

[tools.commitizen]
# ...
changelog_merge_prerelease = true

And then you'll have to run

cz changelog

Sample snippet:

mkdir /tmp/cz-test && cd /tmp/cz-test
git init
cz init # press enter for everything
echo "changelog_merge_prerelease = true\n" >> .cz.toml
git add . && git commit -m "feat: start"
cz bump -pr rc
touch file1 && git add file1 && git commit -m "feat: add file1"
cz bump -pr rc
touch file2 && git add file2 && git commit -m "feat: add file2"
cz bump
cz changelog
cd -
rm -rf /tmp/cz-test

Commitizen docker image

Mentioned because a breaking change is introduced. We use cz as the entrypoint.
Check the repo commitizen-docker-image for more info.

Template updated with v3

The template to create plugins has been updated to support v3.

Full changelog below

v3.0.0 (2023-04-23)

BREAKING CHANGE

• Plugins are now exposed as commitizen.plugin entrypoints

Feat

• init: add new settings
• add semver support through version provider new api (#686)
• changelog: add merge_prereleases flag
• providers: add a scm version provider
• providers: add support for some JSON-based version providers (NPM, Composer)
• providers: add support for some TOML-based versions (PEP621, Poetry, Cargo)
• providers: add a commitizen.provider endpoint for alternative versions providers
• plugins: Switch to an importlib.metadata.EntryPoint-based plugin loading

Fix

• init: welcome message
• small corrections and clean up
• major version zero message
• update dependencies
• commands/changelog: use topological order for commit ordering
• excepthook: ensure traceback can only be a TracebackType or None

[master d07c029] bump: version 2.42.1 → 3.0.0
4 files changed, 30 insertions(+), 4 deletions(-)