リリースフローと設計

tagpr はリリース準備をプルリクエストとして扱います。そのプルリクエストのマージによってリリース内容を承認し、作成されたタグを起点としてリリースフローを開始します。

なぜリリースプルリクエストなのか

ソフトウェアのリリースには、見落としやすいものの重要な小さな変更が伴うことがよくあります。

• 次のバージョンを選ぶ。
• バージョンファイルを更新する。
• changelog またはリリースノートを準備する。
• 依存関係または生成ファイルを更新する。
• プロジェクト固有の準備コマンドを実行する。
• 正しいコミットにタグを付ける。

これらの手順を 1 人のメンテナーのマシンで手動実行すると、暗黙的になり、レビューが難しくなります。tagpr は準備をプルリクエストに移し、提案されたリリースを実施前にメンテナーとコントリビューターが確認できるようにします。

このプルリクエストは自動化の出力であると同時に、例外に対応するための逃げ道でもあります。tagpr が定型的な変更を準備する一方で、メンテナーは同じリリース PR ブランチに、例外的なリリース作業をコミットできます。

設計原則

• 判断ではなく提案を自動化する。 tagpr は候補バージョン、changelog、ファイル変更を準備します。メンテナーはマージ前にレビューして調整できます。
• 通常のプルリクエストワークフローを使う。 リリースの知識をメンテナーのローカルコマンドだけに置いてはいけません。開発で使うレビューと承認の流れを、リリース準備にも適用します。
• タグをリリースフローの起点にする。 マージでリリースコミットを承認し、タグでリリース対象のソースとバージョンを一意に示します。その後、ビルド、パッケージ化、公開、デプロイが tagpr 自体の一部になることなく、そのタグを利用できます。
• GitHub をリリース情報の情報源として再利用する。 tagpr は独自のリリースデータベースやワークフローを導入せず、マージ済みプルリクエスト、ラベル、生成リリースノート、GitHub Actions、GitHub Releases を基盤にします。

これにより、リリース前からプロセスが見えるようになります。メンテナーとユーザーは、公開されたリリースプルリクエストで提案内容とバージョンの両方を確認できます。

ライフサイクル

リリースブランチは tagpr.releaseBranch で設定する長期存続ブランチです。リリースプルリクエストのベースであり、リリースコミットを受け取ります。リリース PR ブランチは、tagpr がプルリクエストのヘッドとして管理する一時的な tagpr-from-* ブランチです。

以下の例では、リリースブランチとして main を使います。

1. main が進むとリリースプルリクエストが作成される

main が最新のリリースタグより先に進むと、tagpr は自動的にリリース PR ブランチとリリースプルリクエストを作成します。デフォルトでは、プルリクエストは次の処理を行います。

• 次のバージョンを提案する。
• 設定されたバージョンファイルを更新する。
• GitHub の生成リリースノートから changelog を更新する。
• リポジトリにリリースノート設定がない場合は作成する。

緑の線はリリースブランチ main、珊瑚色の線はリリース PR ブランチです。番号付きの吹き出しは、tagpr の自動処理とメンテナーのレビュー・マージ判断を区別しています。tagpr は最新の main からリリース PR ブランチを更新するため、図ではブランチポイントとマージ結果が main 上で隣接します。マージ結果が新しいヘッドとなり、tagpr が再度実行され、そのコミットにバージョンタグを付け、GitHub Release も作成できます。

この図は概念を示したものです。tagpr は GitHub のすべてのマージ方法、つまり Create a merge commit、Squash and merge、Rebase and merge に対応しています。

2. 開いたリリースプルリクエストは main を追跡する

リリースプルリクエストを開いたまま main がさらに進むと、tagpr はプルリクエストを自動的に更新します。最新の main からリリース PR ブランチを再作成してリリース変更を適用し直すため、メンテナーが手動で rebase しなくても rebase に似た結果になります。

図では、薄く表示された経路が以前のブランチ状態、実線の珊瑚色の経路が更新後の状態です。

3. メンテナーはリリースプルリクエストを調整できる

リリースプルリクエストは読み取り専用の自動化出力ではありません。メンテナーはリリース PR ブランチに直接コミットして、リリース前に必要な作業を行えます。たとえば次のような作業です。

• 正確なバージョンを選ぶ。
• リリースノートを編集する。
• 依存関係または生成ファイルを更新する。
• その他のプロジェクト固有のメタデータを変更する。

繰り返し可能なファイル変更は tagpr.command で自動化できます。これはバージョンファイルの更新前に実行されます。または、更新後に実行される tagpr.postVersionCommand を使えます。実行の詳細は リリース準備コマンド を参照してください。

main が進んだ後に tagpr がプルリクエストを更新すると、これらの追加コミットを、再作成したリリース PR ブランチへ引き継いで保持しようとします。更新図のひし形は、この方法で保持された手動コミットを表しています。

自動生成された変更と手動で調整した変更を確認したら、プルリクエストをマージして内容を承認し、リリースを開始します。

4. リリースを開始したいときにマージする

リリースプルリクエストはリリーススケジュールを強制しません。すぐにマージする必要はなく、開いたままにしておくことが想定されています。メンテナーがマージを決めるまで、次のリリースを継続的に更新して表示します。

つまり、未リリースの変更がある場合、通常は開いたリリースプルリクエストが 1 つ存在します。このプルリクエストは急いで閉じるべき未完了作業ではなく、見えるリリースキューとして扱ってください。

常に開いたプルリクエストがプロジェクトに合わない場合は、頻繁にマージして小さなリリースを作るのもよい方法です。小さく段階的なリリースなら、1 回にレビューして出荷する変更量を減らせ、リリースキューも短期間で解消できます。

マージ後、tagpr は結果のコミットにタグを付けます。そのタグを起点としてプロジェクト固有のリリースフローが開始されます。tagpr は必要に応じて GitHub Release も作成します。

下流のビルド、パッケージ化、公開、デプロイでは、Action の tag 出力またはタグをトリガーとする別ワークフローを利用できます。詳細は タグ付けとリリース を参照してください。

バージョンファイルとタグ

バージョンファイルには 2 つの役割があります。

1. tagpr はリリースプルリクエストの準備中に提案をそのファイルへ書き込む。
2. tagpr はマージ後にそのファイルを読み、最終タグを決定する。

これにより、プルリクエスト内のバージョン編集が最優先になります。バージョンファイルがないプロジェクトでは tagpr.versionFile = - を設定し、タグを唯一のバージョン情報源として使えます。

Changelog と GitHub Release

tagpr は GitHub の生成リリースノートを使って CHANGELOG.md と GitHub Release の本文を準備します。カテゴリと除外は .github/release.yml または .github/release.yaml で制御します。

これらの動作は個別に設定できます。

• tagpr.changelog = false は changelog の更新を無効にする。
• tagpr.release = false は GitHub Release の作成を無効にする。
• tagpr.release = draft は draft の GitHub Release を作成する。

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

tagpr が行わないこと

tagpr はリリースを準備し、その起点となるタグを作成します。GitHub Release も作成できますが、パッケージのビルド、レジストリへのアップロード、デプロイはプロジェクト固有のままです。これらを tagpr の外に置くことで、各プロジェクトが独自のリリースツールを使いつつ、承認済みのリリース内容と一貫したタグを利用できます。

GitHub Releases を immutable にするリポジトリでは、公開前にアセットを添付する必要があります。tagpr と下流のリリースツールの責任分担については、Immutable Releases の活用と連携 を参照してください。