x.y.zの各桁は次を表す。
| 桁 | 上がるとき | 例 |
|---|---|---|
x |
ワールドの保存形式が変わったとき | 次元フォルダの構成が変わった |
y |
機能を足した、または外したとき | LZ4を読めるようにした |
z |
不具合を直したとき | パレットの並び順を直した |
全言語で同じ番号を使う。ある言語だけ1.1.0ということはしない。
Minecraftが更新されても、保存形式が変わらなければxは上がらない。
形式が同じなら新しいバージョンのワールドもそのまま扱えるので、ライブラリ側で対応することが無い（adr/0003）。
xが上がるのは、扱える形式の下限（MIN_SUPPORTED_DATA_VERSION）を引き上げるときである。
それまで使えていたワールドが使えなくなるため、いちばん上の桁で知らせる。
xを上げるときはyとzを0に戻す。
まず、形式が変わったかどうかを確かめる。 変わっていなければ何もしなくてよい。
-
実ワールドを用意する。新バージョンで新規ワールドを作り、ネザーとエンドにも行って各次元を生成させる
-
走査する。
python3 spec/tools/scan_world.py "<新しいワールド>" --verboseルート直下キー・セクションキー・
Statusの出現数が出るので、spec/30 / spec/40の記述と照らし合わせる -
差が無ければここで終わり。そのバージョンのワールドはすでに扱える。確認した記録として
TARGET_DATA_VERSIONを上げてもよいが、必須ではない
形式が変わっていた場合だけ、次へ進む。
-
仕様書を直す。推測ではなく実データを根拠に書き直す
-
実装を新しい形式へ合わせる
-
MIN_SUPPORTED_DATA_VERSIONを新しい形式が入ったバージョンへ上げ、TARGET_DATA_VERSIONも更新する。csharp/src/SpringNBTLibrary/SpringNbt.cs java/src/main/java/io/github/scriptarts/springnbt/SpringNbt.java typescript/src/index.ts python/src/spring_nbt_library/__init__.py rust/src/lib.rs -
テストベクタを作り直す。
python3 spec/tools/build_testdata.py
-
全言語のテストと適合性検証を通す
-
次のリリースでは、タグの版の
xを上げる（4章）
source spec/tools/env.sh
# 各言語のテスト
(cd csharp && dotnet test)
(cd java && mvn test)
(cd typescript && npm test)
(cd python && python -m pytest tests)
(cd rust && cargo test)
# 全言語の挙動一致（このライブラリでいちばん肝心な点）
./spec/run-conformance.sh
# ドキュメントと実装の一致
python3 spec/tools/check_docs_sync.py
python3 spec/tools/check_links.py
# コメントと禁止記法の規約適合
python3 spec/tools/check_comments.py
# 実ワールドでの検証
python3 spec/tools/scan_world.py "<ワールドのパス>"すべて通ることがリリースの条件である。 1つでも落ちている状態で出すと、「全言語で挙動が同じ」という本ライブラリ唯一の売りが嘘になる。
版を書くのは、リリースのタグ（v1.2.3）とCHANGELOG.mdの節の見出し（## [1.2.3]）の2か所だけである。
パッケージ設定などに版を書き写して回ることはしない。
- 各言語のパッケージ設定（csproj、pom.xml、package.json、pyproject.toml、Cargo.toml）とロックファイルの版は、常に仮の版
0.0.0のままにしておく。releaseワークフローが、組み立てる直前にタグの版をspec/tools/set_version.pyで書き込む。lintワークフローは、リポジトリ内で0.0.0から変わっていないかを調べる - 導入手順の例（言語別のREADMEと
docs/getting-started/）は、具体的な版の代わりに<版>と書く - 適合性検証ツールの
versionコマンドは、ライブラリの版を出さない
そのため、リリースで手を動かすのは次の2つだけになる。
CHANGELOG.mdに## [<版>]の節を作り、変更点を書く- その版のタグを打ってpushする（5章）
CHANGELOGの節はリリースの必須条件である。 リリースの本文はここから組み立てるので、節が無いとワークフローが落ちて公開まで進まない。
gitのタグで参照したRustのクレートは、Cargo.tomlの版が0.0.0のまま見える。中身はそのタグのものである。
GitHub Releasesへビルド済みの成果物を置く。 利用者はそれを落として自分のプロジェクトへ組み込む。
git tag -a v<版> -m "v<版>"
git push origin v<版>vで始まるタグをpushするとreleaseワークフローが動き、次を行う。
- タグから版を取り、各言語のパッケージ設定へ書き込む
CHANGELOG.mdからリリース本文を組み立てる（その版の節が無ければここで止まる）- 全対応言語のテストと適合性検証を通す（落ちたら公開しない。正しく動かないものを配らないため）
- 言語ごとの成果物を組み立てる
SHA256SUMS.txtを作る- Releasesを作って成果物を添付する
| 言語 | ファイル | 中身 |
|---|---|---|
| C# | SpringNBTLibrary.<版>.nupkg |
NuGetパッケージ（ローカルのソースとして使う） |
| C# | SpringNBTLibrary-<版>-dotnet8.zip |
.dllと.xml（補完用）、LICENSE、README |
| Java | spring-nbt-library-<版>.jar |
|
| TypeScript | spring-nbt-library-<版>.tgz |
ビルド済みJSと型定義 |
| Python | spring_nbt_library-<版>-py3-none-any.whl / .tar.gz |
wheelとsdist |
| Rust | spring-nbt-library-<版>.crate |
ソースのtar.gz |
Rustはgit参照が主な使い方になる。Cargoはgitリポジトリを直接依存にできるので、ファイルを落とす必要がない。.crateはネットワークに繋がらない環境向けの控えである。
releaseワークフローは手動でも起動できる。
Actionsの画面からRun workflowを選ぶと、成果物の組み立てまでを行い、Releasesは作らずにartifactsとして残す。
このときの版は、CHANGELOG.mdのいちばん新しい節のものを使う。
中身を確かめてからタグを打てる。
本文は2つを継いで作る。
| 部分 | 出どころ |
|---|---|
| 変更点 | CHANGELOG.mdの## [<版>]の節 |
| 案内文 | .github/release-common.md |
組み立てるのはspec/tools/release_notes.pyで、リリースのワークフローが呼ぶ。手元でも確かめられる。
python3 spec/tools/release_notes.py 1.1.0変更点の実体をCHANGELOG.md側に置いているのは、同じ内容を2か所へ書かせないためである。節が無ければ組み立てが失敗するので、変更点を書き忘れたまま公開することがない。
リポジトリ内への相対リンクは、そのタグを指す絶対URLへ書き換える。 リリースのページからは相対リンクを辿れないため。