From 27be1efa66bfe36ebaf1b8810b65c1c59da02cae Mon Sep 17 00:00:00 2001 From: Krzysztof Macewicz Date: Sun, 27 Sep 2026 10:27:53 +0200 Subject: [PATCH] wip: 0.1.0rc1 and 0.1.0-rc.1, the first candidates through the release workflow Co-Authored-By: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 51 ++++++++++++++++++++++++++++++++++++ docs/publishing.md | 43 ++++++++++++++++++++++++++++++ docs/weather-starter.md | 4 +-- python/README.md | 7 ++--- python/src/sde/__init__.py | 2 +- typescript/README.md | 7 ++--- typescript/package-lock.json | 4 +-- typescript/package.json | 2 +- 8 files changed, 108 insertions(+), 12 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..43dbf5c --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,51 @@ +# Changelog + +The two libraries are released separately, one tag per language: `python-v*` to PyPI and +`typescript-v*` to npm ([`docs/publishing.md`](docs/publishing.md) §5). A shared version number does +not make them agree. What does is the conformance suite and +[`conformance/contract-version.txt`](conformance/contract-version.txt). + +## `smart-data-engine-sdk` 0.1.0rc1 and `@smart-data-engines/sde` 0.1.0-rc.1 + +These are the first release candidates published through the release workflow. They cover +everything since `0.1.0.dev0`, the development release that claimed the PyPI name on 12 September +2026. + +**Runtimes.** Python 3.11 to 3.14 and Node 18 to 26, every version tested in CI +([`docs/platforms.md`](docs/platforms.md)). + +**Placement maps and moving data.** +- Map contract 5 carries a physical design for each group: key order, a time partition, and indexes + from a closed vocabulary. It is checked against the engine's own catalogue + ([`docs/physical-design.md`](docs/physical-design.md)). +- Write generations are enforced by the engine. Migration verification is bound to the project, the + immutable map and the group. +- The local operator, `sde-operator`, handles all copy and index work: + - it executes and recovers signed cutovers; + - it stages fresh copies, also within one engine; + - it builds, removes and replaces indexes in place, without a copy or a write pause; + - it abandons a staging that cannot finish. + +**Sessions.** +- Both languages have bounded batch writes, point reads, keyset scans, counts and exact numeric + summaries. +- Session and transaction ownership. +- Verified TLS to both engines ([`docs/engine-connections.md`](docs/engine-connections.md)). +- Values keep their precision. Timestamps keep their microseconds in TypeScript reads and in + ClickHouse parameters from Python, and ClickHouse JSON numbers stay exact. + +**Telemetry.** The window document reports three things: +- each operation's shape; +- the fields each read filtered on, by name only; +- the group's size, index share, daily growth, time-filtered share and write burstiness + (`Session.measure_storage()` / `session.measureStorage()`), as numbers only. + +**The Weather starter.** `sde-weather` (Python) and `sde-weather-ts` make up a local, recoverable +customer starter ([`docs/weather-starter.md`](docs/weather-starter.md)): +- restricted runtime credentials; +- point, analytics, fleet and alerts workloads; +- operator handoffs; +- an ownership-checked reset. + +**Releasing.** A release is a per-language tag, behind a gate, artefact checks and OIDC publishing +with no stored credential. The npm dist-tag is chosen from what the registry already holds. diff --git a/docs/publishing.md b/docs/publishing.md index b1f9fe9..60091b3 100644 --- a/docs/publishing.md +++ b/docs/publishing.md @@ -660,3 +660,46 @@ the attestation itself rather than leaving it to a flag somebody has to remember What makes that acceptable rather than merely tolerable: the version without an attestation is `0.1.0-dev.0`, matching the `0.1.0.dev0` already on PyPI. It is a dev release, so **every version a client would actually pin is attested** — the gap lands on the one release nobody depends on. + +### 5.5 The first release through the workflow: `0.1.0rc1` and `0.1.0-rc.1` + +These are release candidates, and that is deliberate. The pipeline has never run, and a candidate is +the number this section says to spend on the first run (§5). Do the steps in this order, because each +one needs the one before it. + +1. **PyPI.** Add the trusted publisher (§5.3, item 1). Then revoke both API tokens from the + 12 September upload, on TestPyPI and on PyPI: Account settings → API tokens → Remove. Deleting the + uploaded files does not revoke a token. +2. **npm, by hand, once** (§5.3, item 2). Publish `0.1.0-dev.0` from the last commit before the + version bump, meaning the bump commit's parent. Then configure the trusted publisher: + + ```bash + BUMP= + git fetch origin + git worktree add /tmp/sde-npm-bootstrap "$BUMP^" + cd /tmp/sde-npm-bootstrap/typescript + grep '"version"' package.json # "0.1.0-dev.0" + npm ci + npm login + npm publish --access public --tag latest + npx npm@11.15.0 trust github @smart-data-engines/sde \ + --repo Smart-Data-Engines/smart-data-engine-sdk --file release.yml --env npm + ``` +3. **GitHub.** Require two-factor authentication for the organisation + ([`github-security.md`](github-security.md)). It is off today. +4. **The two tags**, both on the bump commit: + + ```bash + git tag python-v0.1.0rc1 "$BUMP" && git push origin python-v0.1.0rc1 + git tag typescript-v0.1.0-rc.1 "$BUMP" && git push origin typescript-v0.1.0-rc.1 + ``` + + Then approve each deployment: Actions → the release run → Review deployments. On npm the + candidate becomes `latest`, because no final version exists yet (§5.2). +5. **Verification from the registries**, which is ours. A clean environment installs + `smart-data-engine-sdk==0.1.0rc1` from PyPI and `@smart-data-engines/sde@0.1.0-rc.1` from npm. It + runs the shared conformance vectors against the installed packages and the Weather starter end to + end. `0.1.0` is bumped only after that passes. +6. **The documents that describe registry state change afterwards**, not before: + `docs/implementations.md`, `docs/weather-starter.md` and `python/tests/_claims.py`. The npm link + also goes onto the landing page (§5.3, item 2). Until the publish they say what is true. diff --git a/docs/weather-starter.md b/docs/weather-starter.md index 9501ea9..19606de 100644 --- a/docs/weather-starter.md +++ b/docs/weather-starter.md @@ -15,9 +15,9 @@ wheel and npm tarball. In fresh application directories: ```sh python3 -m venv .venv -.venv/bin/python -m pip install './smart_data_engine_sdk-0.1.0.dev0-py3-none-any.whl[signed,postgres,clickhouse]' +.venv/bin/python -m pip install './smart_data_engine_sdk-0.1.0rc1-py3-none-any.whl[signed,postgres,clickhouse]' npm init -y -npm install ./smart-data-engines-sde-0.1.0-dev.0.tgz pg +npm install ./smart-data-engines-sde-0.1.0-rc.1.tgz pg ``` `setup`, `doctor` and `run` refuse before writing anything when a binding's driver cannot be imported, diff --git a/python/README.md b/python/README.md index 52a0708..ff3b7d4 100644 --- a/python/README.md +++ b/python/README.md @@ -131,8 +131,9 @@ including portable keyset pages, typed values and explicit failure semantics. ## Local Weather starter -The unreleased [Weather starter](https://github.com/Smart-Data-Engines/smart-data-engine-sdk/blob/main/docs/weather-starter.md) -installs from reviewed artifacts and exercises logical operations with restricted runtime credentials. -It includes local setup, telemetry, operator handoffs and an ownership-checked reset. +The [Weather starter](https://github.com/Smart-Data-Engines/smart-data-engine-sdk/blob/main/docs/weather-starter.md) +is part of this package, as the `sde-weather` command. It exercises logical operations with +restricted runtime credentials, and it includes local setup, telemetry, operator handoffs and an +ownership-checked reset. Engine credentials and verified TLS configuration: [connection guide](../docs/engine-connections.md). diff --git a/python/src/sde/__init__.py b/python/src/sde/__init__.py index aa92240..4a0e74f 100644 --- a/python/src/sde/__init__.py +++ b/python/src/sde/__init__.py @@ -156,7 +156,7 @@ class Meta: from .write_fence import EPOCH_COLUMN as WRITE_EPOCH_COLUMN from .write_fence import FenceState, WriteFence -__version__ = "0.1.0.dev0" +__version__ = "0.1.0rc1" __all__ = [ "ALSO_WRITE_SINCE", diff --git a/typescript/README.md b/typescript/README.md index bb8f476..50135ee 100644 --- a/typescript/README.md +++ b/typescript/README.md @@ -140,9 +140,10 @@ including portable keyset pages, typed values and explicit failure semantics. ## Local Weather starter -The unreleased [Weather starter](https://github.com/Smart-Data-Engines/smart-data-engine-sdk/blob/main/docs/weather-starter.md) -installs from reviewed artifacts and exercises logical operations with restricted runtime credentials. -It includes local setup, telemetry, operator handoffs and an ownership-checked reset. +The [Weather starter](https://github.com/Smart-Data-Engines/smart-data-engine-sdk/blob/main/docs/weather-starter.md) +runs its workloads from this package, as the `sde-weather-ts` command, with restricted runtime +credentials. Setup, the local operator and the ownership-checked reset are the Python package's +`sde-weather` command. ## Test-tool dependencies diff --git a/typescript/package-lock.json b/typescript/package-lock.json index c9e3826..595b3de 100644 --- a/typescript/package-lock.json +++ b/typescript/package-lock.json @@ -1,12 +1,12 @@ { "name": "@smart-data-engines/sde", - "version": "0.1.0-dev.0", + "version": "0.1.0-rc.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@smart-data-engines/sde", - "version": "0.1.0-dev.0", + "version": "0.1.0-rc.1", "license": "Apache-2.0", "bin": { "sde-weather-ts": "bin/weather.mjs" diff --git a/typescript/package.json b/typescript/package.json index b667317..0c0fabb 100644 --- a/typescript/package.json +++ b/typescript/package.json @@ -1,6 +1,6 @@ { "name": "@smart-data-engines/sde", - "version": "0.1.0-dev.0", + "version": "0.1.0-rc.1", "description": "Smart Data Engine client library: declare a data model, we place it and move it", "license": "Apache-2.0", "homepage": "https://github.com/Smart-Data-Engines/smart-data-engine-sdk",