バージョン¶

arkhe は Semantic Versioning 2.0.0 に従う。 MAJOR.MINOR.PATCH。

版はまだ 0.x——1.0 までを参照。いま出ている版は文書に書かない （リリースのたびに古くなるため）。変更履歴を見ること。

版が何を約束するか¶

SemVer は「公開されている面」を決めて初めて意味を持つ。ライブラリではなく基盤なので、その範囲は「公開している関数」より広い。

約束に含まれるもの	破壊的変更の例
解決の振る舞い	inflection が答えなくなる。ステータスコードが変わる。suffix passthrough が祖先で解決しなくなる
REST API	項目の削除・改名。今まで通っていた要求が通らなくなる
環境変数	設定項目の改名・削除。既定値の変更が振る舞いを変える
CLI	コマンドやオプションの削除・改名。スクリプトが読む出力の形が変わる
DB スキーマ	既存の台帳に適用できない、あるいはデータを失うマイグレーション
不変条件	いずれかが弱まること（下記）

含まないもの: 内部のモジュール構成、管理画面のマークアップ、ログの書式、compose/ の中身（あれは見本）。

不変条件は契約の一部¶

これらの拒否こそが arkhe の存在理由である。署名が 1 つも動かなくても、いずれかが弱まれば MAJOR とする。

一度公開した名前が、理由なしに・打ち直しなしに・届く範囲の外から消せるようになる（消せること自体は在る——狭く、跡を残して。0.4.0 で意図して開けた口であり、そう書いた）
名前空間が削除できるようになる
取り下げた名前が、ふたたび採番の対象に戻る
retired から戻せるようになる
採番が黙って更新に化けうるようになる
到達範囲がリクエストで広がるようになる
人の主体が API キーを持てる、機械の主体が外部ログインで名乗れる

これらを黙ってやるリリースは、関数の署名を壊すリリースより悪い。壊れるのがビルドではなく識別子だから。

マイグレーション¶

MINOR でマイグレーションを追加してよい。ただしデータを失ってはならない。 出す前に毎回、PostgreSQL に対して upgrade → downgrade → upgrade を通す（scripts/check.sh）——SQLite は PostgreSQL が弾くスキーマを通してしまうため。

台帳は作り直せない。NR の下では失った ARK を採り直せないので、多くのサービスが持つ「元のシステムから再投入する」という逃げ道が、ここには無い。

1.0 まで¶

版が 0 で始まる間は、MINOR が破壊的変更を運ぶ。0.1.0 → 0.2.0 は壊れうるが、 0.0.1 → 0.0.2 は壊さない。

1.0 を打つのは:

ARK の適合状況に未対応が残っていないこと、
実際のマイグレーションを 1 度は越えてスキーマが安定したこと、
最初の 1 組織以外が動かしていること。

それまでは版を固定して使うこと。

リリースの手順¶

# 1. 版と変更履歴（その版の節と、両方のリンク定義）
vim pyproject.toml CHANGELOG.md CHANGELOG.ja.md && uv lock

# 2. 確かめるだけ。**何も出さない**（こちらが既定）
bash scripts/release.sh v0.1.0

# 3. 出す。タグ → push → GitHub のリリース
bash scripts/release.sh v0.1.0 --publish

# 4. 変更履歴のページを追随させる
bash scripts/deploy-docs.sh

確かめる作業と出す作業を分けてある。 2 は安く何度でもできるが、タグと GitHub のリリースは取り消せない。--publish を付けない限り何も出ない。

スクリプトは、タグと pyproject.toml が一致すること、両方の変更履歴にその版の節とリンク定義があること、未リリースの比較リンクが新しい版を起点にしていることを確かめてから先へ進む。それ以外は pyproject.toml から決まる——パッケージも OpenAPI も管理画面もそこから読む。0.x は GitHub 上でプレリリースとして出す（版の番号を安定性の主張と取り違えさせないため）。