Pythonパッケージの新しいバージョンを作成する#
キーポイント
Pythonのパッケージのバージョンを(上げる)ときは semantic versioning guidelines (SemVer)のルール に従ってください。例えばメジャーバージョンアップ(バージョン1.0 --> 2.0)は、ユーザーにとってパッケージのコードを変更することに相当します。
パッケージのバージョン管理には、hatch_vsc のようなプラグインを使うことを検討するとよいでしょう - GitHub でのみリリースを行うワークフローを作りたいのであれば。
その他、Hatch、Flit、PDMなどの主要なパッケージビルドツールには、パッケージのバージョンを更新するためのバージョン機能があります。
パッケージのバージョン番号をコード内で手作業で更新するのは避けましょう！
pyOpenSciでは、Pythonパッケージの新しいバージョンにリリース値を割り当てる際に、 semantic versioning guidelines を使用することを推奨している Python PEP 440 に従うことを推奨しています。
Semantic versioning は、パッケージのバージョンを更新するためのアプローチで、パッケージのコードに加えようとしている変更の種類と程度を考慮します。パッケージのバージョンを更新する方法とタイミングを一貫させることは、次のように重要です:
これは、あなたのユーザ (あなたのパッケージに依存している他の開発者を含むかもしれません) がパッケージの変更範囲を理解するのに役立ちます。
標準的なルールに基づいて、開発チームがパッケージのバージョンを上げるタイミングを判断するのに役立ちます。
センバーのルールに従った一貫したバージョンの増加とは、パッケージのバージョンの値が、バージョンごとにコードベースで行われた変更の程度を説明することを意味します。こうしてパッケージのバージョン番号は、コードの変数にうまく名前をつけることで コードを表現豊かにする ことができるのと同じように、 "表現豊かに" なります。
バージョン管理について
場合によっては、小さなバージョン変更でさえも、パッケージのアップデートを一部のユーザーにとって破壊的な変更に変えてしまう可能性があります。 さらに重要なのは、コードのバージョンアップ方法を文書化することであり、可能であればコードの非推奨ポリシーも文書化することです。
SemVerルール#
SemVerに従って、パッケージのバージョンを上げます:
パッチ (1.1.1 --> 1.1.2)
マイナー (1.1.1 --> 1.2.1)
メジャー (1.1.1 --> 2.1.1)
バージョン番号は以下のルールに基づいて変更されます:
バージョン番号MAJOR.MINOR.PATCHが与えられたら、インクリメントする:
MAJOR version 互換性のないAPIの変更を行った場合
後方互換性のある方法で機能を追加する場合の MINOR version 。
PATCH version 後方互換性のあるバグ修正を行う場合 プレリリースとビルドのメタデータ用の追加ラベルは、MAJOR.MINOR.PATCHフォーマットの拡張として利用できます。
注釈
バージョン管理にはcalverを好んで使う人もいます。リリースされたバージョンに関連する日付の値に依存することを考えれば、より使いやすいシステムかもしれません。 しかし、calverは、新しいバージョンがいつ既存のビルドを壊すかもしれないという感覚をユーザーに提供しません。 そのため、semverをお勧めします。
pyOpenSciは、パッケージがバージョニングに対して合理的なアプローチを持っている限り、査読でsemverを要求することはありません！
Python パッケージのバージョン番号を手動で更新するのは、できる限り避けてください。#
パッケージのバージョンの値を複数の場所で持ちたい場合がよくあります。 その一例として、パッケージの version の属性であると同時に、ドキュメントの中で呼び出されることがあります。
ヒューマンエラーを避けるため、パッケージのバージョン番号の手動更新は 避けることをお勧めします。 バージョン番号は一箇所にまとめておく方がよいでしょう。
もし1カ所のバージョンを実装できないのであれば、hatchやPDM、bump2versionのような、パッケージ全体でバージョン値を更新してくれるツールの使用を検討しましょう。
以下では、Pythonパッケージのバージョン更新を管理するために使用できるいくつかのツールについて説明します。
Pythonパッケージのバージョンを管理するツール#
パッケージのバージョンを管理するために使用できる、科学的なエコシステムで広く使われているツールがいくつかあります。 これらのツールのいくつかは、あなたが選択した この章で議論するパッケージングビルドツール に組み込まれているか、それらと連携しています。
以下に、これらのツールの概要を示します。
パッケージのバージョンを管理するために使用できるツールには、一般的に3つのグループがあります:
セマンティックリリースツール: これらのツールは、コミットメッセージのテキストから、使用するバージョンバンプのタイプを自動的に判断します。 以下では、セマンティックバージョニングアプローチを実装したPythonツールとして、 Python Semantic Release を取り上げます。
手動インクリメンタルバンプツール: Hatchのようなツールは、パッケージ内でのバージョンバンプを提供します。通常、これはコマンドリンクで実装されます。例えば、
hatch version majorはプロジェクトを0.xから1.0にします。バージョン管理システムツール: 最後に、バージョンを追跡するためにバージョン管理システムに依存するツールがある。 これらのツールは、パッケージビルドツールのプラグインであることが多いです (例：setuptools build または hatchling)。 以下では、パッケージリポジトリの管理に .git tags と GitHub を使用していることを前提に、このオプションについて説明します。
セマンティックリリース、バージョン管理ベースと手動バージョンバンプの比較#
一般的に、セマンティックリリースツールやバージョン管理システムツールは、GitHub Actionsを使ってGitHub上で自動的に実行するように設定することができる。 つまり、GitHub のリリースとそれに関連する新しいバージョンのタグを使って、自動ビルドのトリガーとなるワークフローを作れるということです:
パッケージをビルドし、新しいタグに従ってバージョンを更新します。
ビルドをテストし、テスト用PyPIに公開します。
パッケージをPyPIに公開します
注釈
パッケージのバージョンを上げるとは、パッケージのバージョンに一定の 変更が加えられた後に、そのパッケージのバージョンを上げることです。 たとえば、あるパッケージのバージョン 0.8 から 0.9 にバンプしたり、0.9 から 1.0 にバンプしたりします。
セマンティックバージョニングを使用する場合、3つの主な "レベル" が考えられます:
メジャー、マイナー、パッチ。 これらの詳細については後述します。
Pythonパッケージのバージョンを上げるツール#
このセクションでは、Pythonパッケージのバージョンを管理するための以下のツールについて説明します:
hatch &
hatchling 用 hatch_vcs プラグイン
setuptools-scm
python-semantic-version
ツール1: インクリメンタルバージョニングを提供するHatchやその他のビルドツール#
最近のビルドツールのフロントエンドツールの多くは、セマンティックバージョン管理のルールに従ったバージョンサポートを提供しています。 これらのツールは Python Semantic Version とは異なり、バージョンを実装するために特定のコミットメッセージを必要としません。 そうではなく、コマンドラインで次のようなコマンドを使ってバージョンを更新することができます:
tool-name version update majortool-name version update minor
例えば、Hatch は、パッケージのバージョンをインクリメンタルに変更する hatch version minor を提供しています。 Hatch の場合、バージョン値はpyproject.tomlファイルにあります。
Hatch（またはPDMのような他のツール）の長所#
1つのツールを使ってローカルで簡単にバージョン更新ができます！
Hatch（またはPDMのような他のツール）の短所#
パッケージのバージョンがパッケージ全体で更新されるようにするには、いくつかの設定が必要です。
ツール 2: Hatch_vcs & hatchling ビルドバックエンド#
hatch_vcsは、 git tags を使ってパッケージのバージョンを管理できるバージョン管理ツールです。Hatch_vcs はパッケージの現在のバージョンを追跡する _version.py ファイルをパッケージのエコシステムに作成します。
Hatch はパッケージのバージョンを _version.py ファイルに記録しています。 Hatchが管理する単一のファイルにバージョンを保存することで、パッケージにバージョン番号の "単一の真のソース" 値を提供します。 これにより、パッケージのバージョンを手動で更新することに伴う潜在的なエラーを排除することができます。
あなた（またはあなたのCIシステム）がパッケージをビルドするとき、hatchはあなたのパッケージの現在のタグ番号をチェックします。 もし増加していれば、新しい値で _version.py ファイルを更新します。
このように、新しいタグを作成したり、タグ付きの新しいリリースを作成してパッケージをビルドすると、Hatchは新しいタグの値にアクセスし、それを使ってパッケージのバージョンを更新します。
hatch_vcs を使用するには、 hatchling ビルドバックエンドを使用する必要があります。
Tip
日々のワークフローにそれらを好むなら、Hatchlingは Flit や PDM を含む最新のビルドツールでも使用できます。
pyproject.tomlでのHatchのセットアップ例#
# pyproject.toml example build setup to use hatchling and hatch_vcs
[build-system]
requires = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"
Hatch_vcs は完全に自動化されたパッケージのリリースとビルド、GitHub上のPyPIへのプッシュのワークフローをサポートしています。
# Example hatch vcs setup in the pyproject.toml file
[tool.hatch.build.hooks.vcs]
version-file = "_version.py"
Tip
もしあなたが setuptools_scm を使っているのであれば、 hatch_vcs と hatchling があなたの現在のsetuptools/ビルドワークフローと現代的に同等であることがわかるかもしれません。
hatch_vcs Pros#
Hatchは最新のPythonパッケージング標準をサポート
これは、あなたのパッケージバージョンを含む単一ソースファイルを作成します。
パッケージのバージョンを手動で更新することはありません
ドキュメンテーションを含め、パッケージのどこにでもバージョンを書くことを自動化できます！
純粋にGitHubベースのリリースワークフローをサポートしています。 これにより、メンテナンスのワークフローが簡素化されます。
バージョン番号は隠された
_version.pyファイルを通してパッケージ内で更新されます。 手動で設定を更新する必要はありません。私たちは詳細なコミットメッセージを好みますが(下記のPython Semantic Versionを参照してください)、パッケージを管理する際にコミットメッセージに関する特定のガイドラインを適用したり管理したりするのが難しい場合があることも知っています。
hatch_vcs Cons#
CIワークフローでは、GitHubのタグを使ってバージョン番号を手動で入力したり作成したりすることになります。 しかし、タグのバージョンを "bump" するビルドをローカルで開発することもできます。
ツール4: Pythonセマンティックリリース#
Python semantic release はコミットメッセージのワークフローを使い、コミットメッセージに含まれるキーワードに基づいてパッケージのバージョンを更新します。 その名の通り、Python Semantic Release は semver release のルールに従います。
Python Semantic Release では、git のコミットメッセージにある特定の言語を使ってバージョンをトリガーします。
例えば、 fix(attribute_warning): という言葉は、Python Semantic Releaseが patch バージョンバンプを実装する引き金になります。 例えば、あなたのパッケージのバージョンが1.1.0で、fix(text-here) と書かれた以下のコミットをした場合、Python Semantic Release はあなたのパッケージをバージョン1.1.1にします。
$ git commit -m "fix(mod_plotting): fix warnings returned athlete attributes"
同様に、機能（feat()）はマイナーバージョンアップの引き金となります。 例えばバージョン1.1からバージョン1.2へ
git commit -m "feature(add_conversions): add value conversions to activity date"
Tip
このPythonパッケージガイド で、pythonのセマンティックバージョンについての丁寧な議論を見つけることができます。なお、このガイドは2020年以降更新されておらず、今後も更新される可能性があります！しかし、今のところ、いくつかのコマンドは古いが、内容は依然として素晴らしいです。
Pythonセマンティックリリースの長所#
センバーのバージョニングに忠実に従う
説明的なコミットメッセージを使ってメンテナを強制します。これにより、トラブルシューティングを簡素化し、よりクリーンで自己記述的なgit履歴を確保することができます。
Pythonセマンティックリリースの短所#
動作させるには、非常に特殊なコミット言語が必要です。 実際には、メンテナや貢献者の中にはコミットメッセージにそのレベルの具体性を保てない人もいるでしょう (注意: リポジトリ内の git commit メッセージをチェックするボットがあります)。
リリースはコマンドラインで行われます。 このため、GitHub ベースのリリースワークフローを実装するのが難しくなります。間違ったコミットメッセージがリリースのトリガーになってしまう可能性があるからです。
バージョン番号は、
pyproject.tomlのような設定ファイルとパッケージの _version.py ファイルの間で手動で更新されます。