Breaking changes and deprecations
Handling of breaking changes and deprecations
Breaking changes
Breaking changes are defined as a change to any of the following that cause compilation errors or undesirable runtime behavior to an existing 3rd party consumer application or script after upgrading to the next stable minor version of a Dapr artifact (SDK, CLI, runtime, etc):
- Code behavior
- Schema
- Default configuration value
- Command line argument
- Published metric
- Kubernetes resource template
- Publicly accessible API
- Publicly visible SDK interface, method, class, or attribute
Breaking changes can be applied right away to the following cases:
- Projects that have not reached version 1.0.0 yet
- Preview feature
- Alpha API
- Preview or Alpha interface, class, method or attribute in SDK
- Dapr Component in Alpha or Beta
- Interfaces for
github.com/dapr/components-contrib - URLs in Docs and Blog
- An exceptional case where it is required to fix a critical bug or security vulnerability.
Process for applying breaking changes
There is a process for applying breaking changes:
- A deprecation notice must be posted as part of a release.
- The breaking changes are applied two (2) releases after the release in which the deprecation was announced.
- For example, feature X is announced to be deprecated in the 1.0.0 release notes and will then be removed in 1.2.0.
Deprecations
Deprecations can apply to:
- APIs, including alpha APIs
- Preview features
- Components
- CLI
- Features that could result in security vulnerabilities
Deprecations appear in release notes under a section named “Deprecations”, which indicates:
- The point in the future the now-deprecated feature will no longer be supported. For example release x.y.z. This is at least two (2) releases prior.
- Document any steps the user must take to modify their code, operations, etc if applicable in the release notes.
After announcing a future breaking change, the change will happen in 2 releases or 6 months, whichever is greater. Deprecated features should respond with warning but do nothing otherwise.
Announced deprecations
| Feature | Deprecation announcement | Removal |
|---|---|---|
| GET /v1.0/shutdown API (Users should use POST API instead) | 1.2.0 | 1.4.0 |
| Java domain builder classes deprecated (Users should use setters instead) | Java SDK 1.3.0 | Java SDK 1.5.0 |
Service invocation will no longer provide a default content type header of application/json when no content-type is specified. You must explicitly set a content-type header for service invocation if your invoked apps rely on this header. | 1.7.0 | 1.9.0 |
gRPC service invocation using invoke method is deprecated. Use proxy mode service invocation instead. See How-To: Invoke services using gRPC to use the proxy mode. | 1.9.0 | 1.10.0 |
The CLI flag --app-ssl (in both the Dapr CLI and daprd) has been deprecated in favor of using --app-protocol with values https or grpcs. daprd:6158 cli:1267 | 1.11.0 | 1.13.0 |
| Hazelcast PubSub Component | 1.9.0 | 1.11.0 |
| Twitter Binding Component | 1.10.0 | 1.11.0 |
| NATS Streaming PubSub Component | 1.11.0 | 1.13.0 |
Workflows API Alpha1 /v1.0-alpha1/workflows being deprecated in favor of Workflow Client | 1.15.0 | 1.17.0 |
Migration of http-max-request-size flags/annotations to max-body-size. See How-To: Handle larger body requests | 1.14.0 | 1.17.0 |
Removal of the workflow instance ID reuse policy. The IGNORE and TERMINATE actions on ID conflicts are no longer supported: creating a workflow whose instance ID belongs to a running workflow always fails with a conflict. SDK options that still expose the policy (such as reuse_id_policy in the Python SDK) are deprecated and silently ignored by 1.18+ runtimes. | 1.18.0 | 1.18.0 |
| Workflow instance ID reuse requires the whole workflow tree to be terminal. Recreating a completed, failed, or terminated workflow’s instance ID is rejected while any child workflow created by its previous execution (checked recursively) is still running. Use unique instance IDs, or purge the workflow to free its ID unconditionally. | 1.18.2 | 1.18.2 |
The standalone Placement service is planned for deprecation in 1.21, when the Scheduler serves actor placement by default. From 1.19 you can opt in early with the Helm value global.scheduler.placement.enabled=true (false by default). See Placement service. | 1.19.0 | Not yet scheduled |
Python SDK: dapr.ext.grpc topic handlers whose event parameter is not annotated with SubscriptionMessage receive the deprecated cloudevents.sdk.event.v1.Event type, and subscribe() emits a DeprecationWarning. Annotate handlers with dapr.ext.grpc.SubscriptionMessage. From Python SDK 1.20, unannotated handlers receive SubscriptionMessage. From Python SDK 1.21, the dapr[grpc] extra no longer installs cloudevents. | Python SDK 1.19.0 | Python SDK 1.22.0 |
Python SDK: the top-level flask_dapr package is a shim that emits a FutureWarning. Import from dapr.ext.flask instead. import dapr also emits a FutureWarning when an old dapr-ext-* or flask-dapr package is installed. Uninstall these packages and install the matching extras of dapr, for example pip install "dapr[fastapi,workflow]". The shim and both warnings remain through Python SDK 1.21. | Python SDK 1.19.0 | Python SDK 1.22.0 |
Python SDK: the reuse_id_policy parameter of schedule_new_workflow has no effect and emits a DeprecationWarning. An instance ID can be reused once the existing instance is in a terminal state. Remove the argument. | Python SDK 1.18.3 | Python SDK 1.21.0 |
Python SDK: a gRPC endpoint with an http:// or https:// prefix, for example https://grpc.example.com:443 in DAPR_GRPC_ENDPOINT, emits a DeprecationWarning (a UserWarning before 1.19). Use host:port?tls=true or host:port?tls=false instead. These endpoints keep working. | Python SDK 1.19.0 | Not yet scheduled |
Related links
- Read the Versioning Policy
- Read the Supported Releases