We follow Semantic Versioning for compatibility between Dagster releases.
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:
dagster package, unless they're marked experimental.@public decorator.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.
The "superseded" 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.
Superseded APIs do not have a known scheduled removal point, but we recommend avoiding them in new code.
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.
Unlike superseded APIs, deprecated APIs have a known scheduled removal point. We will provide guidance on when to expect the removal.
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:
Dagster deployments can have multiple versions of Dagster running simultaneously.
A Dagster deployment consists of a set of code locations, as well as host processes: the web server and daemon.
Code locations within a deployment can each depend on a different Dagster version.
Host processes within a deployment are expected to have the same Dagster version. That Dagster version is expected to be greater than or equal to the greatest Dagster version used by any code location within the deployment.
In Dagster+ deployments, Dagster+ automatically keeps host processes up-to-date so no user action is required.
In OSS deployments, users are expected to upgrade their host processes before upgrading the version of Dagster used in their code locations.
Each Dagster release strives to support the currently active versions of Python.
When a new version of Python is released, Dagster will work to add support once Dagster's own core dependencies have been updated to support it. Note: Some external libraries may not always be compatible with the latest version of Python.
When a version of Python reaches end of life, Dagster will drop support for it at the next convenient non-patch release.
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.