From c092edbab0e8b516faaa459f6d0915c7df3cd06f Mon Sep 17 00:00:00 2001 From: Sho Sakuma Date: Wed, 6 May 2026 06:09:43 +0900 Subject: docs: clarify paper/velocity compatibility Add a dynamic compatibility matrix (GitHub Releases + ProtocolVersion.kt at each tag) shown on the home page, download page, and a new reference doc. Split protocol theory and rolling-update rules out of the Velocity feature guide into the new compatibility reference, and simplify the download notice. Also set explicit GitHub release titles in the Paper / Velocity workflows so the awkward paper/v* tag prefix is not the user-facing label. Co-Authored-By: Claude --- website/src/docs/reference/compatibility.md | 57 +++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 website/src/docs/reference/compatibility.md (limited to 'website/src/docs/reference/compatibility.md') diff --git a/website/src/docs/reference/compatibility.md b/website/src/docs/reference/compatibility.md new file mode 100644 index 0000000..dc0c3b2 --- /dev/null +++ b/website/src/docs/reference/compatibility.md @@ -0,0 +1,57 @@ +--- +layout: doc +--- + +# Paper / Velocity 互換性 + +LunaticChat の Paper プラグインと Velocity プラグインは独立にバージョン管理されています．それぞれの組み合わせが動作するかどうかは，両プラグインに埋め込まれた**プロトコルバージョン**で判定されます． + +## 結論から + +- **両プラグインの最新版同士は常に互換性があります．** 迷ったら両方を最新にしてください． +- 古いバージョンを混在させたい場合は，下のマトリクスで組み合わせを確認してください． +- 接続状態は Minecraft サーバーで `/lcv status` を実行すると確認できます． + +## 互換性マトリクス + +各セルは「その Paper × Velocity の組み合わせが接続できるか」を示します．データは GitHub Releases から自動取得されます． + + + +## プロトコルバージョンとは + +Paper / Velocity 間の通信は LunaticChat 独自のプラグインメッセージプロトコルで行われています．プロトコルにはセマンティックバージョニング (`MAJOR.MINOR.PATCH`) が振られており，接続時のハンドシェイクで両者のバージョンが照合されます． + +判定ルールは以下です： + +- **MAJOR** が一致すること +- 相手の **MINOR** が自分の `MIN_SUPPORTED_MINOR` 以上かつ自分の `MINOR` 以下であること +- **PATCH** は判定に影響しない + +`MIN_SUPPORTED_MINOR` は「どこまで古い MINOR を受け入れるか」を示す値で，ローリングアップデート中の猶予期間を作るために使われます． + +### バージョンバンプの基準 + +| レベル | 変更例 | 互換性 | デプロイ順序 | +|--------|--------|--------|-------------| +| **PATCH** (1.0.0 → 1.0.1) | optional フィールド追加，新 sub-channel 追加 | 完全互換 (`ignoreUnknownKeys=true` で安全) | 順不同，いつでも | +| **MINOR** (1.0.x → 1.1.0) | required フィールド追加，既存 sub-channel のセマンティクス変更 | `MIN_SUPPORTED_MINOR` の範囲内で後方互換 | **Velocity を先に更新** → 各 Paper を順次更新 | +| **MAJOR** (1.x.x → 2.0.0) | ワイヤフォーマット変更，sub-channel 削除/リネーム | 非互換 | **全サーバー同時デプロイ** | + +### ローリングアップデートの考え方 + +1. **プロトコル変更なし**：Paper / Velocity を独立にデプロイ可能．プラグインのバグ修正やリファクタはここに入ります． +2. **PATCH 変更**：どちら側からでも自由にデプロイ可能． +3. **MINOR 変更**：Velocity を先行更新し，`MIN_SUPPORTED_MINOR` で旧 Paper を許容．全 Paper 更新後に `MIN_SUPPORTED_MINOR` を引き上げ． +4. **MAJOR 変更**：メンテナンスウィンドウで一括更新． + +## ハンドシェイクの挙動 + +接続時は以下の流れで互換性が確認されます： + +1. Paper サーバー起動時に Velocity に対してハンドシェイクを送信 +2. Velocity が自身のプロトコルバージョンと照合 +3. 不一致の場合は接続が拒否され，状態が `FAILED` になる +4. ハンドシェイクのタイムアウトは 5 秒 + +接続状態は `/lcv status` で確認できます．詳細は [Velocity 連携](/docs/features/velocity#接続状態) を参照してください． -- cgit v1.2.1