Document Python 0.1.0 support status

Author: TonisOrmisson

CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this reference implementation are documented here.
+
+## 0.1.0 — unreleased
+
+First public reference implementation of the OpenStatSpec strict wide-table
+SPSS profile.
+
+### Included
+
+- Import of unencrypted SAV and ZSAV sources into one dedicated wide SQL table
+  and its metadata catalog.
+- Export of supported dataset semantics to SAV and ZSAV.
+- SQLite, PostgreSQL, and MySQL/MariaDB profiles, including service-backed
+  PostgreSQL and MySQL CI coverage.
+- Preflight checks for target profile limits, atomic imports, validation, a
+  command-line interface, and machine-readable capability and loss reports.
+
+### Important boundaries
+
+- This release promises semantic round-trip equivalence only for supported
+  features; it never promises byte-identical SAV/ZSAV output.
+- The adapter requires explicit `allow_loss` consent before exporting known
+  unsupported or lossy dictionary semantics.
+- Multiple-response sets, variable alignment, variable sets, and custom
+  attributes have explicit capability diagnostics; see the SAV profile.
+- Encrypted SPSS files are not supported.

README.md

@@ -37,6 +37,22 @@ openstatspec import responses.sav --database-url postgresql+psycopg://... --data
 openstatspec export --database-url postgresql+psycopg://... --dataset-id responses-2026 --output responses-roundtrip.sav
 ```
 
-The initial scaffold deliberately declares no conforming SPSS or SQL profile.
-The entry points are stable, but fail explicitly until an implementation has
-been proven by OpenStatSpec conformance fixtures.
+## 0.1.0 support status
+
+The adapter supports unencrypted SAV and ZSAV import and SAV/ZSAV export for
+the semantics exposed by its SPSS engine. SQLite is the local reference path.
+PostgreSQL and MySQL/MariaDB are also covered by service-backed CI conformance
+checks. Use these explicit SQLAlchemy URLs:
+
+- SQLite: `sqlite:///dataset.sqlite`
+- PostgreSQL: `postgresql+psycopg://user:password@host/database`
+- MySQL/MariaDB: `mysql+pymysql://user:password@host/database`
+
+Run `openstatspec capabilities` before an integration to inspect the
+machine-readable feature matrix. Export is deliberately strict: if known
+dictionary semantics cannot be reproduced, it stops until you pass the exact
+diagnostic code with `--allow-loss`. This avoids silent loss while making an
+intentional lossy export auditable.
+
+See [the SAV profile](docs/sav-profile.md) for feature boundaries and
+[release readiness](docs/release-readiness.md) for the pre-tag checklist.

docs/release-readiness.md

@@ -0,0 +1,44 @@
+# 0.1.0 release readiness
+
+This page records the expected release contract, not a publication event.
+Creating a version tag remains a separate maintainer action.
+
+## Supported workflow
+
+For a supported unencrypted SAV or ZSAV source, the adapter imports one source
+dataset into exactly one dedicated wide data table plus catalog tables. It can
+validate that representation and export it back to SAV or ZSAV.
+
+## SQL profiles
+
+| Profile | Connection URL | Verification |
+| --- | --- | --- |
+| SQLite | `sqlite:///dataset.sqlite` | Local reference fixture |
+| PostgreSQL | `postgresql+psycopg://…` | GitHub Actions PostgreSQL service |
+| MySQL/MariaDB | `mysql+pymysql://…` | GitHub Actions MySQL service |
+
+The MySQL service test establishes the shared MySQL/MariaDB profile contract.
+It is not a claim that every MariaDB release or configuration has separately
+been tested.
+
+## Export-loss policy
+
+`capability_matrix()` and `openstatspec capabilities` expose the current
+feature state. Before export, the adapter combines source and writer
+diagnostics. An export with known loss fails unless the caller passes the
+relevant diagnostic codes through `allow_loss` or repeats `--allow-loss CODE`
+in the CLI.
+
+Known boundaries include multiple-response sets, variable alignment, variable
+sets, and custom attributes. A caller that supplies consent receives the
+machine-readable loss report with the export result.
+
+## Maintainer checks before tagging
+
+1. Run `python -m pytest`.
+2. Run the service-backed profile checks with configured PostgreSQL and MySQL
+   URLs, or confirm the GitHub Actions SQL-services job is green.
+3. Build with `python -m build` and install the generated wheel in a clean
+   environment.
+4. Confirm `openstatspec capabilities` reflects the intended support boundary.
+5. Review this document, the README, and CHANGELOG for accurate scope.

docs/sav-profile.md

@@ -13,17 +13,20 @@ measurement level, user-missing rules, file notes, and source encoding
 metadata. User-missing values remain stored values; their interpretation is
 kept as metadata and is restored to SAV on export.
 
-## Declared SQL profiles
+## Verified SQL profiles
 
-SQLite is the tested reference profile. PostgreSQL and MySQL/MariaDB have
-explicit preflight declarations but need live-server conformance fixtures
-before they are described as tested. An import that exceeds a target's strict
-single-table column limit fails before it creates a dataset.
+SQLite has a local reference fixture. PostgreSQL and MySQL/MariaDB have
+service-backed conformance checks in GitHub Actions that import, validate, and
+export the same supported fixture. The MySQL service test verifies the shared
+MySQL/MariaDB profile contract; it does not claim separately tested coverage
+for every MariaDB release or server configuration. An import that exceeds a
+target's strict single-table column limit fails before it creates a dataset.
 
 ## Explicit current boundaries
 
 - Imports accept unencrypted `.sav` and `.zsav` sources through pyreadstat.
-- Export currently writes `.sav` only. Requesting `.zsav` fails explicitly.
+- Exports write SAV and ZSAV; ZSAV output uses the engine's compressed
+  SAV writer path.
 - The writer restores metadata supported by pyreadstat. SPSS dictionary
   constructs that pyreadstat does not expose as stable writer inputs—such as
   multiple-response sets and variable sets—are not silently claimed as

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openstatspec"
-version = "0.0.0"
+version = "0.1.0"
 description = "Reference adapter for the OpenStatSpec relational contract"
 readme = "README.md"
 requires-python = ">=3.11"