Skip to content

Python SDK README claims SemVer, but minor releases contain breaking changes #674

Description

@Kydoimos97

The README states:

WorkOS follows Semantic Versioning. Breaking changes are only released in major versions. We strongly recommend reading changelogs before making major version upgrades.

It links to https://semver.org/, which defines SemVer as:

MAJOR version when you make incompatible API changes
MINOR version when you add functionality in a backward compatible manner
PATCH version when you make backward compatible bug fixes

That is not what the Python SDK is currently doing.

Since v8.0.0, every minor release after the major version has included an explicit ⚠️ Breaking section:

A concrete downstream breakage: v8.2.0 includes SDK surface change: Symbol "AsyncPipes.create_data_integration_token" was removed.
Removing public SDK surface area in a minor release is a breaking change, as correctly stated in the release notes, however it directly contradicts the README’s stated versioning policy.

Please either:

  1. follow the documented SemVer policy and only ship breaking SDK changes in major versions; or
  2. update the README to stop claiming SemVer compatibility and clearly tell users that minor SDK releases may contain breaking changes.

This has real downstream consequences because users choose dependency constraints based on the documented compatibility contract. If minor versions can break, production users need to know to pin exact SDK versions instead of trusting 8.x compatibility.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions