セマンティック・バージョニングしたい（commitizen）

$ pip3 install commitizen
$ which cz

commitizenはGitを使ったバージョン管理をサポートしてくれるパッケージです。 コマンド名はczです。 cz サブコマンドするだけで、セマンティック・バージョニングを簡単化できます。

注釈

同じ名前のnpmパッケージがあります。 自分がどちらを使っているのか、混乱しないようにしましょう。

Poetryしたい

$ poetry add commitizen --group dev

Poetryを使ってチームの開発環境を構築している場合を想定しています。 commitizenは開発しているパッケージでは直接使わないため、 devグループに追加します。

初期化したい（cz init）

1$ cd プロジェクト名
2$ cz init

プロジェクトルートで初期化（cz init）して、設定ファイルを作成します。 ターミナルに表示されるダイアログにしたがって矢印キーで選択します。

Pythonパッケージを開発している場合はpyproject.tomlを設定ファイルにするとよいです。 その他の場合は、自分の好みの形式を選択すればよいと思います。 僕は.cz.tomlを選択する場合が多いです。

生成された設定ファイルは次のようになっていました。 最近のPythonパッケージは（暗黙の）ルールとして [tool.パッケージ名]の下に設定を書くようになっています。 （ただの慣習なのか、それを定義したPEPが存在するかは未確認です）

1[tool]
2[tool.commitizen]
3name = "cz_conventional_commits"
4version = "0.0.1"
5tag_format = "$version"

コミットしたい（cz c）

1$ git add ステージしたいファイル名
2$ cz c

czにステージするためのコマンドはありません。 編集したファイルはまずgit addしてステージします。

ステージした状態で、git commitの代わりにcz cを使います。 プロンプトが表示されるので、聞かれた内容に沿って情報を選択／入力するとコミットメッセージができあがります。

コミットメッセージのテンプレートはcz infoもしくはcz schema、サンプルはcz exampleで確認できます。

バージョンアップしたい（cz bump）

1$ cz bump -ch -cc

プログラムの開発にひと区切りついたら、タグをつけましょう。 cz bumpコマンド、これまでのコミットの内容をもとにしたsemverで バージョン番号を更新すると同時に、タグを作成してくれます。 -chオプションを使うと、CHANGELOG.mdを更新できます。 バージョンアップしたり、変更履歴をまとたりする作業はなかなか大変ですが、一発でやってくれるのでとても助かります。

注釈

使い始めてみるとすぐに気が付くと思いますが、 バージョンアップが先か、CHANGELOGの整理が先か問題があります。 僕はバージョンアップをしてから、CHANGELOGを整理することにしています。

バージョン番号を一元管理したい

1[tool]
2[tool.commitizen]
3...
4version_files = [
5    "pyproject.toml:version"
6    "src/__init__.py",
7]

Pythonの場合、バージョン番号を書くファイルに決まりがありません。 src/__init__.pyだったり、src/__version__.pyだったり、 ひと（やチーム）によってさまざまです。

[tool.commitizen.version_files]を設定すると、 これらの外部ファイルにあるバージョン番号も まとめて更新できるようになります。

注釈

commitizenを使ってsemver管理ができるようになっていても、 バージョン情報が書かれたファイルが散逸していては意味がありません。 version_filesで、関係するすべてのファイルを指定するとよいでしょう。