エンジンマニフェストバージョンの更新忘れ

[tarepan]

不具合の内容

概要: エンジンマニフェストがスキーマ更新にも関わらず .manifest_version を更新していない

現象・ログ

以下のように、engine_manifest.json の属性が追加・削除されている。

release-0.13 branch

{
    "manifest_version": "0.13.1",
    "name": "DUMMY VOICEVOX ENGINE",
    "uuid": "c7b58856-bd56-4aa1-afb7-b8415f824b06",
    ...
    "default_sampling_rate": 24000,
    "terms_of_service": "engine_manifest_assets/terms_of_service.md",
    ...
    "dependency_licenses": "engine_manifest_assets/dependency_licenses.json",
    "downloadable_libraries_path": null,
    "downloadable_libraries_url": null
}

release-0.19 branch

{
    "manifest_version": "0.13.1",
    "name": "DUMMY Engine",
    "brand_name": "DUMMY",
    "uuid": "c7b58856-bd56-4aa1-afb7-b8415f824b06",
    ...
    "default_sampling_rate": 24000,
    "frame_rate": 93.75,
    "terms_of_service": "engine_manifest_assets/terms_of_service.md",
    ...
    "update_infos": "engine_manifest_assets/update_infos.json",
    "dependency_licenses": "engine_manifest_assets/dependency_licenses.json",
    "supported_features": {

このように .brand_name / .frame_rate / .supported_features などが属性追加されている。
一方でマニフェストバージョンである .manifest_version は "0.13.1" のままである。

再現手順

branch 比較

期待動作

スキーマ変更時に .manifest_version がバンプされる。

VOICEVOXのバージョン

0.19.0

その他

エンジンマニフェストの全更新履歴を History から調査しました。

• @2022-05-14 (PR 387): マニフェストを manifest_assets/base_info.json として新設（.manifest_version: 0.12.0）
• @2022-05-14 (PR 404): スキーマを変更
• @2022-06-27 (PR 426): manifest_assets/manifest.json へリネームしスキーマを変更
• @2022-07-03 (PR 429): engine_manifest.json へ移動・リネームしスキーマを変更（.manifest_version: 0.13.0）
• @2022-08-03 (PR 437): スキーマを変更
• @2022-09-01 (PR 456): スキーマを変更
• @2022-09-30 (PR 479): Release 0.13.1（.manifest_version: 0.13.1）
• @2022-12-02 (PR 515): スキーマを変更
• @2023-01-09 (PR 567): スキーマを変更
• @2023-02-26 (PR 616): スキーマを変更
• @2023-06-21 (PR 694): スキーマを変更
• @2022-09-30 (PR 1018): スキーマを変更
• @ 2024-01-22 (PR 1008): スキーマを変更
• @2024-01-31 (PR 1035): スキーマを変更

詳細タブにスキーマ変更履歴をまとめました。

PR 404

変更された属性：

• 廃止
  • .icon
  • .terms_of_service
  • .update_infos
  • .dependency_licenses

PR 426

変更された属性：

• 追加
  • .uuid
  • .command
  • .port
  • .version
  • .documents
  • .url
  • .icon

PR 429

変更された属性：

• 追加
  • .terms_of_service
  • .update_infos
  • .dependency_licenses
• 廃止
  • .documents

PR 437

変更された属性：

• 追加
  • .downloadable_libraries_path
  • .downloadable_libraries_url

PR 456

変更された属性：

• 追加
  • .supported_features

PR 515

変更された属性：

• 追加
  • .supported_features.synthesis_morphing

PR 567

変更された属性：

• 追加
  • .brand_name

PR 616

変更された属性：

• 追加
  • .supported_features.manage_library
• 廃止
  • .downloadable_libraries_path
  • .downloadable_libraries_url

PR 694

変更された属性：

• 追加
  • .supported_vvlib_manifest_version

PR 1018

変更された属性：

• 廃止
  • .supported_vvlib_manifest_version

PR 1008

変更された属性：

• 追加
  • .frame_rate

PR 1035

変更された属性：

• 追加
  • .supported_features.sing

約 2 年、ENGINE 0.13.1 時代から ENGINE 0.19.0 にわたり、バージョン bump 忘れが続いていました。その間に約 7 回のスキーマ変更がありました。
「engine_manifest.json 直接読み取り」を採用しているマルチエンジン利用ソフトにとっては、マニフェストバージョンが参考にならず各属性有無を直接確認する、使いづらい状況が続いていた可能性が高いです。

[Hiroshiba]

issue作成ありがとうございます！！

キーを設けた時点では知識がなかったのでちゃんと策定できてなかったのですが、いろいろ考えてようやく仕様が見えてきました。
破壊的変更が起こったとき、つまり今までサードパーティやVOICEVOXが使ってきた方法であろうコードが動かなくなった時にファイルフォーマットのバージョンを上げる形が望ましそうです。

まずサーボパーティアプリ開発者側のニーズとしては、そのファイルフォーマットのバージョンが知りたいのではなく、自分のコードが想定したとおりに動くのかどうかが知りたいはずです。
今回の場合、知りたいのは「マニフェストファイルが想定通りに読めるか」だと思います。
想定通りそうか、というのを未来の変更も含めて提供する手段として、ファイルフォーマットのバージョンが有るのかなと。

エンジンマニフェストファイルは、今までの変更が（たぶん）キーの追加だけなので、マニフェストファイルが想定外になったことはないはずです。
（もちろん、サードパーティアプリ開発者が知ってるkeyのみかどうかをassertしている場合などは別ですが）

ので、バージョンを上げてないのは特に問題なかったと考えています。
追記：と思ったけどちょくちょくキー削除してますね･･･。致命的ではないですが、バージョン変えてないなら良くなかった気がします。

---

そもそもちゃんと仕様が決まっていない＆ドキュメント化されていない点はかなり課題だと思います。

バージョニングをどうしていくかですが、理想的にはライブラリのバージョニングのようにしていく形が良い気がしています。
互換性無視な破壊的変更が加わった場合はメジャーバージョンを、互換性はあるけどフォーマットが変わった場合はマイナーバージョンが上がる感じです。（パッチバージョンはたぶん無い）
まあでもマイナーバージョンが知りたいことは少なく、基本メジャーバージョンだけで良い気がしています。
エディタのRuntimeInfo.jsonはそんな感じです。

VOICEVOXのマニフェストファイルのフォーマットバージョン管理をどうしていくかですが、将来的に破壊的変更をするときに備えて、仕様を変えていったほうが良いかもと思いました。
例えばmanifest_versionは今後使わない値としてしまう、あるいはファイルフォーマットが変わるタイミングでバージョンを999.999.999とかにしてしまうのが良さそう。
代わりにformat_versionとしてマニフェストのファイルフォーマットのメジャーバージョンを提供する、とかをイメージしています。