Releases and Compatibility#

We follow Semantic Versioning for compatibility between Dagster releases.

Dagster core#

Dagster's public, stable APIs will not break within any major release. I.e. if a public, stable API exists in Dagster 1.x.y, upgrading to 1.(x+1).y or 1.x.(y+1) should not result in broken code. If a version does break your code, help us out by filing an issue on Github

Our public, stable Python API includes:

  • All classes, functions, and variables that are exported at the top-level of the dagster package, unless they're marked experimental).
  • Public, non-experimental methods and properties of public, stable classes. Public methods and properties are those show up in the API reference. Within the codebase, they're marked with a @public decorator.

Experimental APIs#

The "experimental" marker allows us to offer new APIs to users and rapidly iterate based on their feedback. Experimental APIs are marked as such in the API reference and usually raise an ExperimentalWarning when used.

Experimental APIs may change or disappear within any release, but we try to avoid breaking them within minor releases if they have been around for a long time.

Deprecated APIs#

The "deprecated" marker indicates that we recommend avoiding an API, usually because there's a preferred option that should be used instead.

Like non-deprecated public stable APIs, deprecated public stable APIs will not break within any major release after 1.0.

Dagster integration libraries#

Dagster’s integration libraries haven’t yet achieved the same API maturity as Dagster core. For this reason, integration libraries remain on a pre-1.0 versioning track (in general 0.y.z of Semantic Versioning; and 0.16+ as of Dagster 1.0.0) for the time being. However, 0.16+ library releases remain fully compatible with Dagster 1.x. We will graduate integration libraries one-by-one to the 1.x versioning track as they achieve API maturity.

While technically the 0.y.z phase of Semantic Versioning is "anything goes", we are conservative about making changes and will provide guidance about when to expect breaking changes:

  • Upgrading to a new dot version within a minor release, e.g. 0.8.1 → 0.8.2, should never result in broken code.
  • An exception to this guarantee is experimental APIs.
  • As often as possible, deprecation warnings will precede removals. E.g. if the current version is 0.8.5 and we want to remove an API, we'll issue a deprecation warning when the API is used and remove it from 0.9.0.
  • Upgrading to a new minor version, e.g. 0.7.5 → 0.8.0 may result in breakages or new deprecation warnings.

Following along#

The best way to stay on top of what changes are included in each release is through the changelog. We call out breaking changes in “Breaking Changes” sections and deprecations in “Deprecations” sections.