Skip to content

Version pairing

The SDK and the API are paired: on connection the client compares its own yousleep_common version with the server's and raises ConnectionError on any difference, patch releases included (strict_version_check=True, the default). This page states the policy and its consequences.

The policy

  1. Exact pairing is the supported mode. Run the same yousleep-common version the API reports (GET /status/version). Every release of this package therefore asks every SDK user to upgrade in lockstep. That cost is weighed before every release.
  2. Under pairing, version numbers have the following meaning:
    • major: the meaning of something that already exists changes: removals, type changes, renamed fields, and changed defaults. A changed default gets a major precisely because pairing makes it invisible: both sides upgrade in lockstep, nothing mismatches, and code that omitted the field silently changes behaviour. The version check cannot catch this class; the release discipline is the guard.
    • minor: additive surface: new endpoints, models, fields, enum members. Safe by construction, because a conforming client is on the same version.
    • patch: fixes within the existing meaning.
  3. The escape hatch guarantees nothing. strict_version_check=False downgrades the mismatch to a warning and is intended as a short-lived operational bridge, for example to read data during an upgrade window. On that path, version skew can surface as a ValidationError in the middle of a call, far from its cause, instead of a clear message at connection time. Do not use it in automation.

What the check does not cover

  • A server that changes mid-session. The comparison runs once, at connection. A deployment that replaces the API under a live client moves the server's version without a new check; a long-lived client spanning a deploy may see skew surface as parsing errors until it reconnects, at which point the check runs again. Rolling updates make this window ordinary. For long-lived processes, connect-time pairing is necessary but not sufficient.
  • Same-shape semantic changes. The check proves both sides agree on which contract, not that the contract's meaning held. That is what the changed-defaults-are-major rule above exists for.