Adopt SemVer 2.0.0 and promote release images by digest
This commit is contained in:
1 parent
2893685aef
commit
b312a50d37
7 files changed
+357
-2
No files matched your search
@@ -13,7 +13,9 @@ runner の環境構築や Gitea の事前疎通診断は行わず、本番へ自
|
||||
| `pageswiki-excalidraw-viewer` | `Dockerfile.excalidraw-viewer` |
|
||||
|
||||
Kroki、Mermaid、code-server は upstream の配布イメージを使用する。
|
||||
`main` / `mk_district` への push、`v*` タグ、手動実行でビルド・公開する。
|
||||
`main` / `mk_district` への push、手動実行でビルド・公開する。
|
||||
`v*` タグは別の `release.yml` でビルド済みイメージを昇格し、再ビルドしない。
|
||||
採番は [SemVer 2.0.0 の運用規則](versioning.md) に従う。
|
||||
本体の `test` ステージで `go test ./...` を実行し、3 イメージのビルドが成功した後に push する。
|
||||
3 回の push は原子的ではないため、**ワークフロー全体の成功を確認してから利用**する。
|
||||
最後に当該ジョブのローカル CI タグと専用 builder を後処理する。
|
||||
@@ -37,6 +39,11 @@ Docker socket を使うジョブは強い権限を持つため、信頼するコ
|
||||
|
||||
### 提示された Docker 版 Runner 3 の構成
|
||||
|
||||
ホストの Docker ソケットを利用する場合は **`docker.io/gitea/runner:3`(通常版)** を使う。
|
||||
`3-dind` / `3-dind-rootless` とソケットの bind mount を混在させない。
|
||||
runner が利用する daemon と `anya-npm-net` が存在する daemon は一致させる。
|
||||
別 daemon に同名ネットワークを作っても接続は共有されない。
|
||||
|
||||
Gitea 側 Compose のラベルで Docker 実行方式を明示する。
|
||||
workflow の `container.image` が実際のジョブ用イメージを指定する。
|
||||
|
||||
|
||||
@@ -0,0 +1,81 @@
|
||||
# バージョニングとリリース
|
||||
|
||||
PagesWiki は [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) を採用する。
|
||||
初回リリースは **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 を確認して利用する。
|
||||
|
||||
```bash
|
||||
# リリース対象のビルド成功済みコミットを明示する。以下は例。
|
||||
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](gitea-images.md) を利用する。
|
||||
Reference in new issue
Block a user