版と互換性#
いまは 1.0 です#
公開 API を壊す前に、非推奨期間を1マイナー以上置きます。 Semantic Versioning のとおりに扱います。
| 0.x（〜0.6） | 1.0 以降（いま） | |
|---|---|---|
| 公開 API を壊す | マイナーで起きうる | 非推奨期間を1マイナー以上置いてから、次のメジャーで消す |
| 内部実装を変える | いつでも | いつでも |
| CHANGELOG に書く | 必ず書く | 必ず書く |
補足
黙って壊すことはしません。 壊れうる変更は必ず CHANGELOG の **「上げる前に見るところ」と「変わったこと（挙動）」**に出します。 上げる前にそこだけ読めば足ります。
落とし穴
約束が始まるということは、直せなくなるものがあるということです。
戻り値の型、record のコンポーネント、public フィールド、interface の abstract、final——
どれも非推奨期間で救えません（同名で代替を置けないので、
「古いほうを残して新しいほうを足す」ができません）。
1.0 の前に、公開 103 パッケージ・署名 4,514 行を通読して片付けてあります
（docs/design-1.0.md）。
どこまでが公開 API か#
パッケージで線を引いています。
| 公開 API | アプリを書くときに触るもの。io.jimble.db、io.jimble.web.server、io.jimble.util.data など |
| 内部実装 | 入口クラスの内側でしかないもの。io.jimble.db.internal.sql.query.*（SQL の内側）、io.jimble.util.internal.json.encoder（Dson の内側）など |
| preview | 外部の仕様に追随するので、下の約束の対象外。いまは io.jimble.mcp.* だけです |
全部の一覧は
docs/api-packages.txt
にあります。
内部は名前で分かります。
io.jimble.<モジュール>.internalから下は、全部内部実装です。
import に internal が出てきたら、それは触ってはいけないものです。
落とし穴
public だから公開 API、ではありません。
Java には「モジュールの外から見えるが、使ってほしくはない」を表す修飾子がないので、
内部実装も public になっています。internal という名前と、上の一覧が線です。
補足
設定ファイルに書く名前と、コマンドで打つ名前は公開 API です。
logback.xml に書く io.jimble.util.log.encoder.LogbackJsonEncoder や、
Gradle を使わない CI で打つ io.jimble.db.cli.JimbleDbCli は、
import されなくても壊せば止まります。だから internal には入れていません。
**この一覧は古くなりません。**パッケージを増やして一覧に書き忘れると、
ApiSurfaceTest が落ちます。サンプル（examples/）が内部パッケージを
import していないかも、同じテストが見ています。
preview——約束の外に置いてあるもの#
io.jimble.mcp.* は 1.0 になっても「壊す前に非推奨期間を1マイナー置く」の対象外です。
MCP は2年で5版が出ており、毎回破壊的な変更が入っています （2026-07-28 では、セッションと GET ストリームが消えました）。 jimble は対応する版を明記して1つだけ実装するという方針なので、 仕様が変わるたびに 「公開 API を壊す」か「仕様に追随しない」かの二択になります。 約束の中に入れると、追随できなくなります。
対応している版は McpProtocol.version() で読めます。
定数ではなくメソッドなのは、public static final String が
アプリのバイトコードへそのまま焼き付くからです——
定数のままだと、jimble を上げてもアプリは古い版の文字列を持ち続け、しかも警告が出ません。
io.jimble.mcp.* を使っているなら、版を上げるときは
CHANGELOG を読んでください。
壊れるときは、必ずそこに書きます。
シグネチャは同じなのに、結果が変わるとき#
ここがいちばん大事なところです。
jimble でこれまで実際に起きた壊れ方は、ほとんどがシグネチャを変えない変更でした——
404 が 405 になる、insertBatch が null を返すようになる、
中断したバッチの履歴が completed から canceled になる。
どれもコンパイルは通るので、上げた側は何も気づきません。
そこで2つに分けて扱います。
| 何をするか | |
|---|---|
| 壊れていたのを直した | **すぐ直します。**非推奨期間は置きません |
| 仕様を変えた | 1.0 以降は、古い動きを1マイナーのあいだ残します |
「壊れていた」に非推奨期間を置かないのは、置けないからです。
たとえば insertBatch は、SQL の揃っていないビルダーを混ぜると
値が横にずれて入っていました。「1マイナーのあいだは、これまでどおり
壊れたデータを書きます」とは言えません。
どちらであっても、CHANGELOG の「変わったこと（挙動）」には必ず出します。 「直した」に埋めて済ませることはしません。
壊すときに何をするか#
- 非推奨にする（1.0 以降）。
@Deprecated(since = "1.2", forRemoval = true)を付け、 javadoc に代わりに何を使うかを書きます - **CHANGELOG に書く。**いつ消えるかも書きます
- **1マイナー以上あけてから消す。**消すのは次のメジャーです
落とし穴
@Deprecated が付いていても、消えるまでは動きます。
ビルドの警告が出るだけです。警告を切らないでください——
消えたことに気づくのが、上げたあとになります。
2.0 で消したもの・変わったものの一覧は 2.0 への移行 にあります。
./gradlew jimbleCheck で、書き換える行を出せます（1.5 では --target=2.0 を付けます）。
版を選ぶ#
公開されているものは Maven Central にあります。 依存の座標と、そのまま動くビルドファイルは Gradle プラグイン にあります。
このドキュメントサイトは、いちばん新しいリリースの内容です（版について）。