Skip to content

Consolidate stale documentation and publish the xerial conformance statement #174

Closed

Description

@magnusp

Purpose

Two finishing moves for the repository, now that the xerial parity queue (#54) is fully drained and no open issues remain:

  1. Consolidate and remove stale documentation. Several root-level documents still describe the project as it was before implementation, or under its old name and layout. They confuse contributors and agents and must be removed, rewritten, or folded into the canonical docs.
  2. Publish an honest xerial conformance statement. State what the driver has reached, what it deliberately excludes, and why, with the compromises a remote Hrana/sqd model forces. This turns "have we reached conformance with xerial?" into a durable, reviewable answer.

Current conformance position

  • Selected subset: 12 xerial test classes plus Utils run against libSQL over Hrana 3 (upstream-xerial_sqlite-jdbc.manifest).
  • Reference probe: the same subset runs against the pinned xerial 3.53.4.0 driver (-Pxerial-control), so a failure there means a bad reference, not a required parity gap.
  • Result at queue close: 268 conformance tests green, 7 skipped; control profile green.
  • Contract: Hrana 3 is the source of truth for transport, values, metadata, batching, transactions, and error reporting; java.sql is the source of truth for the JDBC surface; xerial is a behavioral reference and conformance foundation, never a copy target.

The remaining rejected xerial tests fall into four buckets: native extension API, sqlite-jdbc configuration surface, remote-model semantics (no local file, no shared connection, WAL locking), and build-flag dependence. One JDBC-surface gap is addressable today: savepoints.

Work sequence

#169 (surviving divergence rationale) and #172 (the category taxonomy) both feed #171; #173 lands the one addressable JDBC gap that #171 and #172 name.

Definition of done

  • No root-level document references the old turso-java name, the org.libsql package, or /v2/pipeline.
  • Every module, including libsql-conformance, is listed consistently in README.md and CONTRIBUTING.md.
  • The repository carries one canonical, reviewable conformance statement that names the compromise categories and the one remaining addressable JDBC gap.

Activity

  1. magnusp commented on Oct 24, 2026

    @magnusp
    OwnerAuthor

    All subissues merged to main in fc3f819 via #184, #175, #176, #177, #180, #178, and #181. Savepoints land first, then the documentation consolidation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions