バージョン¶
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 とする。
- ARK や名前空間が削除できるようになる
retiredから戻せるようになる- 採番が黙って更新に化けうるようになる
- 到達範囲がリクエストで広がるようになる
- 人の主体が API キーを持てる、機械の主体が外部ログインで名乗れる
これらを黙ってやるリリースは、関数の署名を壊すリリースより悪い。壊れるのがビルド ではなく識別子だから。
マイグレーション¶
MINOR でマイグレーションを追加してよい。ただしデータを失ってはならない。
CI では毎回 PostgreSQL に対して upgrade → downgrade → upgrade を通す——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
# 2. タグを打つ
git tag -a v0.0.2 -m "v0.0.2" && git push origin v0.0.2
タグでリリースのワークフローが走り、テスト・成果物の作成・その版のドキュメント公開まで
行う。版は pyproject.toml だけで決まる——パッケージも OpenAPI も管理画面もそこから
読むので、他に更新を覚えておく場所は無い。