docs: v0.7.0 release preparation — release notes, upgrade guide, QA hardening

[lukekim]

Summary

Release preparation for v0.7.0 (pom.xml and Version.java are already at 0.7.0 from #50).

Docs

• Release notes (docs/release_notes/v0.7.0.md) now cover the full v0.6.0..trunk delta — the v0.6.0 tag predates feat: add mTLS client certificate support #46, so mTLS client certificates (feat: add mTLS client certificate support #46) and health/readiness/status checks (feat: add health, readiness, and runtime status checks #48) ship for the first time in v0.7.0 alongside the performance overhaul (perf: Native Flight SQL prepared statements, statement caching, and transport tuning (v0.7.0) #50). Dependency table corrected against what v0.6.0 actually shipped (ADBC 0.22.0, no mTLS).
• New upgrade guide (docs/upgrade_guides/v0.6.0-to-v0.7.0.md): drop-in for most apps; documents behavior changes (statement caching on by default, real retry backoff timing, exception-cause type change, auto re-auth, refreshDataset timeout), dependency-tree impacts (ADBC/netty-all removal, Netty 4.1.130, BouncyCastle explicit), and a new-capabilities tour.
• README installation snippets bumped to 0.7.0.

QA performed

• Live runtime: full suite run against a local spiced quickstart (taxi_trips, 2.96M rows accelerated) — 284/284 green, twice consecutively (rerun-safety verified), exercising Flight queries, parameterized queries, dataset refresh (trigger + verify shrink + restore), health/readiness/status, and reset/reconnect paths.
• Mock-only: full suite + SpotBugs green (no runtime present).
• Artifacts: spiceai-0.7.0.jar, -sources.jar, -javadoc.jar build cleanly (mvn package) — the publish pipeline's packaging step is validated.
• Publish workflow preflight: pom.xml ↔ Version.java version consistency check passes (both 0.7.0).

Integration-test hardening (found during live QA)

• testRefreshWithOptionsSpiceOSS was rerun-unsafe: its refresh_sql … LIMIT 10 persists in the accelerated table across runs and refreshes are asynchronous, so a second run against the same runtime failed its 20-row precondition. It now self-heals the precondition, polls for the async refresh instead of a fixed 10s sleep, and restores the dataset afterward.
• Availability probes/skip-paths use one retry instead of zero — resilient live-QA gating, still fast when no runtime is present.

Release steps after this PR merges

1. Publish the draft GitHub release v0.7.0 (already prepared; tag is created on publish, targeting trunk).
2. Publishing triggers .github/workflows/publish.yaml: version check → build → live-runtime make test (needs SPICE_CLOUD_QUICKSTART_API_KEY) → make publish to Maven Central.
3. Watch out for the known flaky "Install Spice CLI" step in that workflow (the installer intermittently resolves an empty release version) — re-run the job if it trips.

[Copilot]

Pull request overview

Prepares the Java SDK for the v0.7.0 release by updating documentation (release notes + upgrade guidance) and hardening integration tests based on live-QA findings so they’re more rerun-safe and resilient to transient runtime availability.

Changes:

• Add v0.7.0 documentation: new upgrade guide and expanded release notes covering the full v0.6.0→v0.7.0 delta.
• Update README install snippets to reference version 0.7.0.
• Harden integration tests by adding a retry to availability probes and making the dataset refresh test poll for async refresh behavior.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/test/java/ai/spice/TpchIntegrationTest.java	Availability probe updated to use one retry.
src/test/java/ai/spice/ResetTest.java	Availability probe updated to use one retry.
src/test/java/ai/spice/ParameterizedQueryTest.java	Local OSS tests updated to use one retry.
src/test/java/ai/spice/FlightQueryTest.java	One-retry availability detection; refresh test made rerun-safe via polling helpers.
README.md	Installation snippets bumped to 0.7.0.
docs/upgrade_guides/v0.6.0-to-v0.7.0.md	New upgrade guide documenting behavior/dependency changes and new features.
docs/release_notes/v0.7.0.md	Expanded release notes with new feature highlights and corrected dependency table.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

src/test/java/ai/spice/FlightQueryTest.java:137

• This test also uses the default maxRetries. To keep the absent-runtime skip path fast under the new exponential backoff (while still allowing one transient retry), set withMaxRetries(1) on the client like the other OSS integration tests.

        try (SpiceClient spiceClient = SpiceClient.builder()
                .build()) {
            String sql = "SELECT tpep_pickup_datetime, total_amount, passenger_count from taxi_trips limit 20;";

src/test/java/ai/spice/FlightQueryTest.java:114

• The refresh OSS integration tests build the client with the default retry count. With v0.7.0’s real backoff, the “no local runtime” skip path can now take ~seconds before the catch block skips. Use a single retry here (matching the other OSS availability probes) to keep the absent-runtime path fast while still being resilient to transient startup blips.

This issue also appears on line 135 of the same file.

        try (SpiceClient spiceClient = SpiceClient.builder()
                .build()) {

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/test/java/ai/spice/FlightQueryTest.java:136

• testRefreshWithOptionsSpiceOSS also uses the builder default maxRetries (3). When the local runtime/dataset is missing, this test’s skip-path will pay the full exponential backoff, which can slow CI/local runs significantly. Setting maxRetries to 1 keeps the gating resilient but avoids the full backoff cost.

        try (SpiceClient spiceClient = SpiceClient.builder()
                .build()) {

src/test/java/ai/spice/FlightQueryTest.java:113

• testRefreshSpiceOSS builds a SpiceClient with the default maxRetries (3). Since retries now use real backoff, the skip-path when no local runtime is present can take ~seconds, which undermines the goal of keeping integration tests fast when the runtime is absent. Consider matching testQuerySpiceOSS above and using a single retry here as well.

This issue also appears on line 135 of the same file.

        try (SpiceClient spiceClient = SpiceClient.builder()
                .build()) {