既存プロジェクトへの tagpr 導入

このガイドでは、すでにバージョン、タグ、changelog、公開自動化があるプロジェクトに tagpr を導入します。過去のリリースを変更したり再公開したりせず、最初の tagpr リリースプルリクエストを予測可能にすることが目的です。

確立したリリースプロセスがない新規プロジェクトでは、代わりに はじめに に従ってください。

ワークフローを有効にする前に

現在のリリース状態を記録します。

• リリース元のブランチ。
• 最新のリリースバージョンと、そのバージョンでタグ付けされたコミット。
• v プレフィックスや monorepo のプレフィックスを含むタグ形式。
• プロジェクトのバージョンを保持するすべてのファイル。
• 既存の changelog と GitHub リリースノート設定。
• タグ、GitHub Releases、パッケージ、デプロイを作成するワークフローまたはスクリプト。

同じバージョンタグを作成したり同じ成果物をリリースしたりできる別のワークフローがある間は、tagpr を有効にしないでください。tagpr が置き換える既存ジョブと、tagpr がタグを作成した後も続けるリリースジョブを決めます。

1. リリースの基準点を確立する

tagpr は、最新の一致するバージョンタグを、リリース済みと未リリースの変更の境界として使います。最新リリースタグについて、次を確認してください。

• 実際にリリースされたコミットを指している。
• tagpr が使う SemVer または CalVer の方式に従っている。
• 期待する v と tagPrefix の値になっている。

たとえば、デフォルト設定で v2.4.0 の後から導入するプロジェクトでは、最初のリリースプルリクエストに v2.4.0 より後の変更が含まれ、ラベルで大きな更新幅を選ばない限り v2.4.1 が提案されるはずです。

一致するタグがない場合、tagpr は v0.0.0 から開始し、リポジトリの最初のコミットからの履歴を対象にします。ワークフローを有効にする前に、その全履歴を受け入れるか、最後にリリースしたバージョンの正確な基準タグを作成してください。公開済みの既存タグを移動または置き換えて基準点を作ってはいけません。

monorepo のインスタンスは、設定された tagPrefix に一致するタグだけを対象にします。メンテナンスブランチでは fixedMajorVersion を使って、別の major リリース系列のタグを無視できます。完全な選択ルールは バージョンとラベルのルール を参照してください。

2. まず設定をコミットする

既存プロジェクトでは、初回実行時の検出に頼らず、ワークフローを有効にする前に .tagpr を作成します。これにより、意図したリリース境界と生成ファイルを、最初のリリースプルリクエストとは独立してレビューできます。

[tagpr]
    releaseBranch = main
    versionFile = version.go,package.json
    vPrefix = true
    changelogFile = CHANGELOG.md

特に次の設定を確認してください。

• releaseBranch はリリースブランチを示し、ワークフローのトリガーと一致する。
• versionFile は tagpr が更新すべきすべてのファイルを列挙する。タグのみのリリースには - を使う。
• vPrefix は既存タグと一致する。
• tagPrefix は monorepo 内で独立してリリースするプロジェクトの範囲を指定する。
• calendarVersioning は、プロジェクトが SemVer を使わない場合に既存の CalVer タグと一致する。

GitHub Action を使う場合、設定ファイルがサブディレクトリにあっても、パスはリポジトリルートからの相対パスです。

最初に設定したバージョンファイルには、現在リリース済みのバージョンを記述してください。tagpr はリリースプルリクエストで、そのファイルを次に提案するバージョンへ更新します。ワークフローを有効にする前に、バージョンファイルと最新リリースタグの不一致を解決してください。

3. changelog とリリースノートの動作を維持する

tagpr は既存の changelog を保持し、生成したエントリを最初のレベル 2 見出しの前に挿入します。独自構造のファイルを使っている場合は、最初に生成された diff を注意深く確認してください。別のプロセスに changelog を任せる必要がある場合は、tagpr.changelog = false を設定します。

GitHub は、プルリクエスト、changelog、GitHub Release で使うリリースノートを生成します。既存の .github/release.yml または .github/release.yaml のルールは引き続き適用されます。tagpr.releaseYAMLPath でカスタムパスを指定する場合は、設定を有効にする前に、そのファイルをリリースブランチに作成してコミットしてください。

生成と設定の詳細は Changelog と GitHub Releases を参照してください。

4. リリースフローを移行する

最初の tagpr リリース前に、次のいずれかのワークフロー構成を選びます。

• steps.tagpr.outputs.tag が空でない場合に、tagpr ワークフロー内で続ける。
• 別のタグトリガーワークフローを維持し、ワークフローを起動できるトークンを tagpr に渡す。GitHub App インストールトークンを推奨する。

リポジトリの GITHUB_TOKEN で作成したタグは、別のワークフローを起動しません。既存のリリースワークフローがタグ push を監視している場合、tagpr がワークフローを起動できるトークンを使わない限り実行されなくなります。

リリース処理は明示的なタグを受け取って実行できるようにして、別のタグを作成せずに失敗したビルド、公開、デプロイなどを再試行できるようにします。両方のワークフロー構成については、タグ付けとリリース を参照してください。

5. tagpr を有効にする

はじめに のワークフローを追加し、GitHub Actions にプルリクエストの作成を許可して、設定とワークフローをリリースブランチへ push します。

tagpr はリリースプルリクエストで GitHub のすべてのマージ方法、つまり Create a merge commit、Squash and merge、Rebase and merge に対応しています。リポジトリで現在使っているマージ設定をそのまま利用できます。リリースプルリクエストは、単独の ref 更新としてマージしてください。無関係なプルリクエストを含むマージキューのバッチでは、プルリクエストごとのリリース境界を tagpr に提供できません。

最初のリリースプルリクエストを確認する

次の確認項目が既存のリリースプロセスと一致するまで、最初のリリースプルリクエストをマージしないでください。

• base_tag と changelog が意図した前回リリースの後から始まっている。
• 提案されたバージョンが期待する次のバージョンである。
• 意図したバージョンファイルと生成ファイルだけが変更されている。
• 既存の changelog の内容が保たれている。
• 生成されたリリースノートが期待するカテゴリと除外を使っている。
• リリースフローがタグ付け後にちょうど 1 回実行される。

履歴範囲や生成された変更が正しくない場合は、プルリクエストを開いたままにします。リリース対象ブランチで .tagpr、基準点、またはリリースノート設定を修正してください。tagpr はリリース提案を再生成します。基準タグまたは tagPrefix を変更すると別のリリース PR ブランチが作られる場合があります。置き換え先を確認してから、不要になったリリースプルリクエストを閉じてください。

提案された SemVer の更新幅を調整する必要がある場合は、リリースプルリクエストでバージョンファイルを編集するか、tagpr:minor または tagpr:major を追加できます。推測されたラベルを変更する前に バージョンとラベルのルール を確認してください。

切り替えを完了する

内容と下流ワークフローの準備ができたら、リリースプルリクエストをマージします。tagpr の再実行後、次を確認してください。

1. 新しいタグがマージされたリリースコミットを指している。
2. GitHub Release と changelog に意図した変更が含まれている。
3. プロジェクト固有のリリースフローが 1 回完了している。
4. 次の未リリース変更によって、次のリリースプルリクエストが作成または更新される。

このリリースが成功したら、以前のプロセスにある不要なタグ作成とリリース作成の手順を削除します。明示的なタグを受け取れる、復旧用のリリースコマンドは残してください。