版と互換性#
いまは 0.x です#
0.x のあいだは、マイナーを上げるときに壊れることがあります。 Semantic Versioning がそう定めていて（1.0 未満は安定を約束しない）、 jimble もそのとおりに扱います。
1.0 からは、公開 API を壊す前に非推奨期間を1マイナー以上置きます。
| 0.x（いま） | 1.0 以降 | |
|---|---|---|
| 公開 API を壊す | マイナーで起きうる | 非推奨期間を1マイナー以上置いてから、次のメジャーで消す |
| 内部実装を変える | いつでも | いつでも |
| CHANGELOG に書く | 必ず書く | 必ず書く |
補足
0.x でも、黙って壊すことはしません。 約束していないのは「壊さないこと」であって、「知らせること」ではありません。 壊れうる変更は必ず CHANGELOG の **「変わったこと（挙動）」**に出します。上げる前にそこだけ読めば足ります。
どこまでが公開 API か#
パッケージで線を引いています。
| 公開 API | アプリを書くときに触るもの。io.jimble.db、io.jimble.web.server、io.jimble.util.data など |
| 内部実装 | 入口クラスの内側でしかないもの。io.jimble.db.sql.query.*（SQL の内側）、io.jimble.util.json.encoder（Dson の内側）など |
全部の一覧は
docs/api-packages.txt
にあります。
落とし穴
public だから公開 API、ではありません。
Java には「モジュールの外から見えるが、使ってほしくはない」を表す修飾子がないので、
内部実装も public になっています。触ってよいかは、上の一覧で見てください。
**この一覧は古くなりません。**パッケージを増やして一覧に書き忘れると、
ApiSurfaceTest が落ちます。サンプル（examples/）が内部パッケージを
import していないかも、同じテストが見ています。
シグネチャは同じなのに、結果が変わるとき#
ここがいちばん大事なところです。
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 が付いていても、消えるまでは動きます。
ビルドの警告が出るだけです。警告を切らないでください——
消えたことに気づくのが、上げたあとになります。
版を選ぶ#
公開されているものは Maven Central にあります。 依存の座標と、そのまま動くビルドファイルは Gradle プラグイン にあります。
このドキュメントサイトは、いちばん新しいリリースの内容です（版について）。