Files
pages/docs/operations/versioning.md
T
Anya Tokugawa b312a50d37
Build and publish container images / images (push) Successful in 10m38s
Release container images / release (push) Successful in 24s
Adopt SemVer 2.0.0 and promote release images by digest
2026-09-27 19:52:58 +09:00

5.2 KiB

バージョニングとリリース

PagesWiki は Semantic Versioning 2.0.0 を採用する。 初回リリースは 0.1.0。Git タグとコンテナタグには接頭辞 v を付ける。 v は SemVer のバージョン番号そのものには含まれない。

互換性の対象

PagesWiki の公開インターフェースとして、設計書・利用手順で公開した次の契約を扱う。

  • HTTP API の URI、認証方式、要求・応答形式、および公開 URI の解決規則。
  • CalDAV / iCalendar 等の外部クライアントとの連携契約。
  • CLI の公開コマンド・オプション、および機械処理向けに明文化した出力形式。
  • 文書化した設定キー、環境変数、インポート/エクスポート形式。
  • 公開した連携アダプタ・システム拡張のインターフェース。

内部関数、DB の内部テーブル構造、非公開エンドポイント、HTML/CSS の内部構造は 安定 API としない。ただし DB・ファイル正本の移行が必要な場合は必ず移行手順と バックアップ条件を記載し、ダウングレード可能とは仮定しない。

番号の更新

変更 1.0.0 以降 初期開発期間 0.y.z の運用
後方互換な不具合修正 PATCH を増やす PATCH を増やす
後方互換な機能追加・公開 API の非推奨化 MINOR を増やし PATCH を 0 に戻す MINOR を増やし PATCH を 0 に戻す
公開インターフェースの非互換変更 MAJOR を増やし MINOR/PATCH を 0 に戻す MINOR を増やし非互換点・移行方法を明記

0.x は SemVer 上の初期開発期間であり、公開 API の安定性はまだ保証しない。 1.0.0 は上記公開契約を安定化させた時点で明示的に採番する。 CI はバージョンを自動で繰り上げない。変更の意味を確認してリリース担当者が選ぶ。

0.2.0-rc.1 等のプレリリースを認める。数値識別子の先頭ゼロは禁止する。 ビルドメタデータ +build.001 は認めるが、バージョンの優先順位には影響しない。 Gitea のコンテナタグは大文字小文字を区別しないため、配布タグの識別子は小文字に限定する。 これは配布側の命名制限であり、SemVer 自体では大文字も有効。

Git とコンテナタグの対応

Git コンテナタグ
通常の main コミット sha-<40桁コミットID>
v0.1.0 v0.1.0
v0.2.0-rc.1 v0.2.0-rc.1
v0.2.0+build.001 v0.2.0_build.001

Docker タグには + を使えないため _ へ置換する。SemVer では _ が使えないので この変換は衝突しない。コンテナタグの 128 文字制限を超えるリリース名は拒否する。 latest、v0、v0.1 等の可変エイリアスは自動更新しない。

リリース手順

  1. main の Build and publish container images が成功したコミットを選ぶ。
  2. 差分・互換性・移行要否を確認し、そのコミットに注釈付き Git タグを付けて push。
  3. Release container images が、そのコミットの SHA タグを digest に解決し、 3 イメージの revision ラベルと既存リリースタグを確認して同名タグへ昇格する。
  4. ワークフロー全体の成功と、ログに記録された 3 つの digest を確認して利用する。
# リリース対象のビルド成功済みコミットを明示する。以下は例。
git tag -a v0.1.0 <成功済みコミットID> -m "PagesWiki 0.1.0"
git push origin refs/tags/v0.1.0

昇格では再ビルドもレイヤーのダウンロードも行わず、元の manifest digest を維持する。 イメージのラベルを後付けで書き換えることもしない(digest が変わるため)。 元の org.opencontainers.image.revision が Git タグのコミットと一致することを確認する。 ソースイメージが欠けていれば停止する。自動でビルドへフォールバックしない。

公開済み Git タグの付け替えや、異なる digest によるリリースタグの上書きを禁止する。 内容を変更する場合は新しいバージョンを発行する。同じ digest の再実行だけは許可する。 3 イメージの更新は原子的ではない。途中失敗時は同じタグのジョブを再実行し、 すでに正しい digest を指しているものはスキップして残りを処理する。

registry の比較・更新は単一トランザクションではないため、リリースは同一 runner で 直列実行し、別クライアントで同じタグを更新しない。管理者は Git の v* 保護と レジストリ側で利用可能なタグ保護も検討する。CI の検査は権限管理の代替ではない。 公開後の SHA タグを再ビルドで更新しても、リリースタグを追従更新してはならない。

本番への自動デプロイはしない。PAGESWIKI_IMAGE_TAG=v0.1.0 のように指定して レジストリ用 Compose を利用する。