バージョンとラベルのルール

tagpr はラベルを使って Semantic Versioning の変更を提案しつつ、最終的なリリースバージョンをリリースプルリクエストでレビューできるようにします。

ラベルのルールは、融通の利かないバージョンポリシーではなく、意見を提案する仕組みとして意図されています。変更が major、minor、patch のどれに当たるかは、プロジェクトの文脈とメンテナーの合意が必要になることがあります。リリースプルリクエストによって判断が見えるようになり、バージョンファイルは明示的な最終上書き手段として残ります。

ラベルには 2 つの異なる層があります。

1. 前回のリリース以降にマージされたプルリクエストに付ける設定可能なラベル。
2. リリースプルリクエストに付ける固定の tagpr:major または tagpr:minor ラベル。

デフォルトの動作

バージョンラベルも編集されたバージョンファイルもない場合、tagpr は patch リリースを提案します。

tagpr/minor と tagpr/major も、コロン形式の代替として受け付けます。major と minor の両方のラベルがある場合は major が優先されます。

tagpr はリリースプルリクエストを識別するために tagpr ラベルも追加します。このラベルはバージョンに影響しません。

マージ済みプルリクエストのラベル

tagpr は前回のリリース後にマージされたプルリクエストを調べます。

• tagpr.majorLabels に列挙されたラベルがあると、tagpr はリリースプルリクエストに tagpr:major を追加する。
• tagpr.minorLabels に列挙されたラベルがあると、tagpr はリリースプルリクエストに tagpr:minor を追加する。
• 設定されたラベルに一致しなければ、提案は patch リリースのままになる。

デフォルトは次のとおりです。

[tagpr]
    majorLabels = major
    minorLabels = minor

値はカンマ区切りで、前後の空白が削除され、ラベル名と完全一致で比較されます。

[tagpr]
    majorLabels = major,breaking-change
    minorLabels = minor,feature,enhancement

この設定では、前回のリリース以降にマージされたプルリクエストのうち、1 件でも一致すればその更新幅が選ばれます。一致するプルリクエストが複数あっても、バージョンが 1 回より多く繰り上がることはありません。

Dependabot のプルリクエスト

dependabot[bot] が作成したプルリクエストのラベルは、バージョン選択では無視されます。Dependabot は依存関係のバージョン変更に応じて major や minor を付けることがありますが、それがプロジェクト自体の同じ変更を意味するとは限らないためです。

依存関係の更新をプロジェクトのバージョンに反映するには、リリースプルリクエストに目的のラベルを直接付けるか、バージョンファイルを編集します。

リリースプルリクエストのラベル

リリースプルリクエストの tagpr:major と tagpr:minor ラベルは、SemVer の提案を直接制御します。マージ済みプルリクエストにバージョンラベルがない場合は、手動で追加できます。

マージ済みプルリクエストから推測されたラベルは、tagpr がリリースプルリクエストを更新するときに再び追加されます。推測された更新幅が適切でない場合は、まず元のプルリクエストのラベルを修正し、その後リリースプルリクエストから対応する tagpr:major または tagpr:minor ラベルを削除してください。先に元を修正しておくと、次回更新時に tagpr が推測ラベルを再追加するのを防げます。あるいは、バージョンファイルで正確なバージョンを選択してください。

バージョンファイルの優先順位

tagpr.versionFile を設定すると、tagpr は提案されたバージョンをそのファイルに書き込み、リリースプルリクエストのマージ後に再度読み取ります。そのため、バージョンファイルに明示的にコミットされたバージョンが、リリースプルリクエストのラベルより優先されます。

複数のバージョンファイルがある場合、最初に設定されたファイルが最終タグを決め、設定されたすべてのファイルがリリース準備の一部として更新されます。

[tagpr]
    versionFile = version.go,action.yml

GitHub Action を使う場合、パスはリポジトリルートからの相対パスです。

タグのみのリリース

Git タグだけをバージョン情報源にする場合は、tagpr.versionFile = - を設定します。

[tagpr]
    versionFile = -

このモードでは、リリースプルリクエストのラベルが最終的な SemVer タグを決めます。デフォルトは patch で、major が minor より優先されます。

Calendar Versioning

tagpr.calendarVersioning を有効にすると、tagpr は設定されたカレンダー形式から次のバージョンを計算します。major と minor のラベルは無視されます。

[tagpr]
    calendarVersioning = YYYY.0M0D.MICRO

バージョンファイルを設定している場合、tagpr はリリースプルリクエストを準備または更新するときに次の CalVer 値を計算し、そのファイルに書き込みます。後日マージされた場合でも、プルリクエストに保存された値がタグになります。

tagpr.versionFile = - の場合、提案は保存されません。tagpr はマージ後にタグを作成するときに CalVer 値を計算します。どちらのモードでも、既存の一致する CalVer タグから次の MICRO 値が決まります。

利用可能な形式トークンは、tagpr.calendarVersioning reference を参照してください。

Monorepo

tagpr.tagPrefix を使うと、バージョン選択の範囲が独立してリリースされるプロジェクトに限定されます。

• 設定されたプレフィックスを持つタグだけが対象になる。
• マージ済み変更の履歴が、プレフィックスで表されるディレクトリに限定される。
• リリースプルリクエストも同じプレフィックスに一致するものが対象になる。

# tools/.tagpr
[tagpr]
    tagPrefix = tools
    versionFile = tools/package.json
    majorLabels = major,breaking-change
    minorLabels = minor,feature

このインスタンスは tools/v* タグと tools/ 以下の変更からバージョンを提案します。

優先順位のまとめ

SemVer リリースでは次の順序になります。

1. 設定したバージョンファイルの明示的なバージョンが最終タグを決める。
2. それ以外では、リリースプルリクエストの tagpr:major または tagpr/major が major を選ぶ。
3. それ以外では、tagpr:minor または tagpr/minor が minor を選ぶ。
4. それ以外では、tagpr が patch を選ぶ。

マージ済みプルリクエストの設定ラベルは、対応するラベルをリリースプルリクエストに追加することで、手順 2 と 3 に反映されます。CalVer を有効にすると、カレンダー形式がこのラベルによる判断に置き換わります。