Repository navigation
Consolidate stale documentation and publish the xerial conformance statement #174
Copy link
Copy link
Closed
Labels
documentationImprovements or additions to documentationImprovements or additions to documentationenhancementNew feature or requestNew feature or request
Description
Purpose
Two finishing moves for the repository, now that the xerial parity queue (#54) is fully drained and no open issues remain:
- 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.
- 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
Utilsrun against libSQL over Hrana 3 (upstream-xerial_sqlite-jdbc.manifest). - Reference probe: the same subset runs against the pinned xerial
3.53.4.0driver (-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.sqlis 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
- Remove the stale PLAN.md implementation plan #167 Remove the stale
PLAN.mdimplementation plan - Rewrite TESTCONTAINERS-USAGE.md against the current code #168 Rewrite
TESTCONTAINERS-USAGE.mdagainst the current code - Add libsql-conformance to the README and CONTRIBUTING module inventory #170 Add
libsql-conformanceto the README and CONTRIBUTING module inventory - Retire IMPLEMENTATION_BUGS_AND_RESOLUTIONS.md or fold it into the conformance statement #169 Retire
IMPLEMENTATION_BUGS_AND_RESOLUTIONS.mdor fold it into the conformance statement - Categorize rejected xerial tests as permanent or addressable #172 Categorize rejected xerial tests as permanent or addressable
- Publish a canonical xerial conformance statement #171 Publish a canonical xerial conformance statement
- Implement JDBC savepoints and re-select the xerial SavepointTest #173 Implement JDBC savepoints and re-select the xerial
SavepointTest
#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-javaname, theorg.libsqlpackage, or/v2/pipeline. - Every module, including
libsql-conformance, is listed consistently inREADME.mdandCONTRIBUTING.md. - The repository carries one canonical, reviewable conformance statement that names the compromise categories and the one remaining addressable JDBC gap.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
documentationImprovements or additions to documentationImprovements or additions to documentationenhancementNew feature or requestNew feature or request
Activity
magnusp commentedon Oct 24, 2026
All subissues merged to main in fc3f819 via #184, #175, #176, #177, #180, #178, and #181. Savepoints land first, then the documentation consolidation.
docs(conformance): make the query string part of the namespace identi…