This is an automated email from the ASF dual-hosted git repository. CritasWang pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/iotdb-client-rust.git
commit d01a2fc85749ea561a31f3111929130155358240 Author: CritasWang <[email protected]> AuthorDate: Fri Jul 17 11:50:08 2026 +0800 Add COMPATIBILITY.md (server version matrix, per-release IDL/Thrift toolchain, SemVer/deprecation policy); CI integration matrix now tests IoTDB 2.0.6 + 2.0.10 --- .github/workflows/ci.yml | 8 +++- COMPATIBILITY.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 +- README_ZH.md | 2 +- 4 files changed, 106 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6e02e1b..ec4b485 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -66,9 +66,15 @@ jobs: integration: runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + # Oldest tested + latest stable IoTDB (see COMPATIBILITY.md). + iotdb-version: ["2.0.6", "2.0.10"] + name: integration (iotdb ${{ matrix.iotdb-version }}) services: iotdb: - image: apache/iotdb:2.0.6-standalone + image: apache/iotdb:${{ matrix.iotdb-version }}-standalone ports: - 6667:6667 steps: diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md new file mode 100644 index 0000000..a4dca0a --- /dev/null +++ b/COMPATIBILITY.md @@ -0,0 +1,97 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# Compatibility & Release Policy + +This document describes which IoTDB server versions this client targets, the +exact protocol toolchain each crate release is built from, and the versioning +rules the crate follows. + +## IoTDB server compatibility matrix + +The client speaks IoTDB service protocol **V3** over Apache Thrift RPC and +targets the IoTDB **2.0.x** line. There is no version-specific branching in +the client code. + +| IoTDB version | Status | Notes | +|---|---|---| +| 2.0.1 | Expected to work | Untested | +| 2.0.2 | Expected to work | Untested | +| 2.0.3 | Expected to work | Untested | +| 2.0.4 | Expected to work | Untested | +| 2.0.5 | Expected to work | Untested | +| 2.0.6 | **Tested** | CI runs the full live test suite + 3 examples against `apache/iotdb:2.0.6-standalone` on every push; TLS verified end-to-end (`enable_thrift_ssl`, TLSv1.3, full certificate verification) | +| 2.0.7 | Expected to work | Untested | +| 2.0.8 | Expected to work | Untested | +| 2.0.10 | **Tested** | Full benchmark + data-correctness verification (all 10 data types, tree & table models, nulls) against a standalone deployment; RPC compression verified (`dn_rpc_thrift_compression_enable=true`) | +| master | Expected to work | The Thrift IDL is synced from `apache/iotdb` master (`iotdb-protocol/`); untested beyond IDL lockstep | +| 1.x | **Not supported** | The table model and the TIMESTAMP / DATE / BLOB / STRING data types assume 2.x; no plan to support 1.x | + +"Expected to work" means the version speaks protocol V3 and the same IDL +surface, but the client has not been exercised against it. Reports of success +or failure on untested versions are welcome as issues. + +## Protocol toolchain (per release) + +Each crate release records the exact IDL source and Thrift toolchain used to +generate `src/protocol/`: + +| Crate version | IoTDB IDL source | Thrift compiler | `thrift` crate | +|---|---|---|---| +| 0.1.0 (unreleased) | `apache/iotdb` master, `iotdb-protocol/` @ `2fedd8a395` (2026-06-30, last change to `client.thrift`/`common.thrift`) | 0.23.0 (as pinned by the IoTDB pom's `thrift.version`) | 0.23 | + +The generation pipeline is documented in [`tools/generate-thrift.sh`](./tools/generate-thrift.sh): +the IDL files (`thrift/client.thrift`, `thrift/common.thrift`) are synced from +`apache/iotdb`'s `iotdb-protocol/` module, and the Thrift compiler binary is +taken from the IoTDB Maven build output, which guarantees the compiler version +matches the one the server project pins. The generated stubs are committed and +must never be hand-edited. + +This table is updated as part of every release. + +## Versioning policy (SemVer) + +The crate follows [Cargo's SemVer rules](https://doc.rust-lang.org/cargo/reference/semver.html): + +- **Pre-1.0 (`0.x.y`)**: a bump of `x` may contain breaking API changes; a + bump of `y` is additive or a bug fix. Cargo treats `0.x` as the + compatibility boundary, so `^0.1` will never auto-upgrade to `0.2`. +- **Post-1.0**: breaking changes bump the major version, new functionality + bumps the minor version, bug fixes bump the patch version. +- A regeneration of the Thrift stubs against a newer IDL is treated as + breaking only if it changes the public Rust API surface; pure wire-level + additions ship as minor/patch releases. + +## Deprecation policy + +- APIs slated for removal are first marked `#[deprecated]` (with a message + pointing at the replacement) and remain functional for at least one minor + release before removal. +- Removals happen only in releases that SemVer already marks as breaking + (major bumps, or `0.x` bumps pre-1.0). +- Deprecations and removals are listed in the release notes. + +## Release process + +- Every release documents, in its release notes: the IoTDB IDL commit, the + Thrift compiler version, and the tested IoTDB server versions (the table + above is updated in the same change). +- CI continuously tests against both the oldest tested and the latest stable + IoTDB versions (currently 2.0.6 and 2.0.10; see + [`.github/workflows/ci.yml`](./.github/workflows/ci.yml)). diff --git a/README.md b/README.md index a403b7d..78ba579 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Working client: session management (with multi-node failover), tablet writes (`i ## Requirements - Rust 1.75+ -- Apache IoTDB 2.x (examples and integration tests use `apache/iotdb:2.0.6-standalone`) +- Apache IoTDB 2.x — see [COMPATIBILITY.md](./COMPATIBILITY.md) for the full server version matrix, the IDL/Thrift toolchain per release, and the SemVer/deprecation policy (CI tests against 2.0.6 and 2.0.10) ## Installation diff --git a/README_ZH.md b/README_ZH.md index 6f62b4f..ae4b026 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -16,7 +16,7 @@ ## 环境要求 - Rust 1.75+ -- Apache IoTDB 2.x（示例与集成测试使用 `apache/iotdb:2.0.6-standalone`） +- Apache IoTDB 2.x — 完整的服务器版本兼容矩阵、每个 release 对应的 IDL/Thrift 工具链版本，以及 SemVer/弃用政策见 [COMPATIBILITY.md](./COMPATIBILITY.md)（CI 针对 2.0.6 与 2.0.10 测试） ## 安装
