Versioning
Every Perspective package is released together under one version: the
@perspective-dev/* npm packages, the perspective-python wheel and the
perspective* Rust crates. major.minor is the compatibility boundary.
Perspective does not follow strict semver: a minor release may contain breaking
changes.
| Release | May contain |
|---|---|
Patch (5.9.1 → 5.9.2) | Fixes and additive features. No breaking API changes, no client/server protocol changes and no saved-config schema changes. |
Minor (5.8.0 → 5.9.0) | Breaking changes to any public API, the client/server protocol, the saved-config schema, defaults, and the minimum supported Node.js, Python or browser versions. Each is listed under Breaking in the changelog. |
Major (4.x → 5.0.0) | Changes to architecture or packaging which need more than a config migration to adopt. |
Removed APIs are not deprecated first: a removal ships in the minor release that
replaces it. Saved configs are covered by
perspective-migrate instead.
Mixing versions
Use the same version of every Perspective package in an application. Within a
major.minor, mixing is tolerated:
- Package ranges. The
@perspective-dev/*npm packages depend on each other with~x.y.zranges, and theperspective*crates with~x.y.zrequirements, so a package manager never pairs releases of different minors.@perspective-dev/clientpins@perspective-dev/serverexactly, because the client’s JavaScript loads the server’s WebAssembly directly. - One
major.minorper page. In the browser, copies of Perspective of the samemajor.minorshare one registry of WebAssembly binaries and runtimes. Each copy of another patch release logs a console warning when it loads, and Perspective’sinit()functions throw when a release of anothermajor.minorhas registered on the same page. - Client and server. A client and a server of the same
major.minorinteroperate over a WebSocket, whatever their patch versions. The protocol has no version handshake, so a mismatch across minor releases is not detected up front: it surfaces as a decode error or as missing fields. - Python and Jupyter.
PerspectiveWidgetloads the@perspective-dev/viewerrelease matching the installedperspective-python, and treatsversionstamps of the samemajor.minoras equal.
Saved configs
save() and saveWorkspace() stamp the version that wrote the token.
- Same
major.minor.restore(),restoreWorkspace()andaddPanel()accept a token saved by any release of the samemajor.minor, older or newer patch. They validate the config’s shape and do not checkversion; when a token fails to restore and was saved by a release of anothermajor.minor, the error names that release. - Older releases.
migrate()upgrades a config written by any release since 2.0.0 to the current schema, and reports what it could not carry over asnotices. It keeps information, not behavior: changed defaults are not reversed. - Newer patch releases.
migrate()passes a config from a newer patch of its ownmajor.minorthrough unmigrated and with itsversionunchanged, with aNewerPatchnotice. The config must still validate against the current types. - Newer minor or major releases.
migrate()rejects the config with aFromFutureerror. validate()checks a config’s shape against the current types and ignoresversion.