mirror of https://github.com/dapr/docs.git
Add build variations + refactor breaking-changes. (#3478)
* Add build variations + refactor breaking-changes. Signed-off-by: Artur Souza <asouza.pro@gmail.com> * Update daprdocs/content/en/operations/support/support-release-policy.md Co-authored-by: Mark Fussell <markfussell@gmail.com> Signed-off-by: Artur Souza <asouza.pro@gmail.com> * Add example and reference to build variants. Signed-off-by: Artur Souza <asouza.pro@gmail.com> * Update daprdocs/content/en/reference/arguments-annotations-overview.md Signed-off-by: Mark Fussell <markfussell@gmail.com> * Update daprdocs/content/en/operations/support/support-release-policy.md Signed-off-by: Mark Fussell <markfussell@gmail.com> * Update daprdocs/content/en/operations/support/support-release-policy.md Signed-off-by: Mark Fussell <markfussell@gmail.com> * Update daprdocs/content/en/operations/support/support-release-policy.md Signed-off-by: Mark Fussell <markfussell@gmail.com> * Update daprdocs/content/en/reference/arguments-annotations-overview.md Signed-off-by: Mark Fussell <markfussell@gmail.com> --------- Signed-off-by: Artur Souza <asouza.pro@gmail.com> Signed-off-by: Mark Fussell <markfussell@gmail.com> Co-authored-by: Mark Fussell <markfussell@gmail.com>
This commit is contained in:
Artur Souza
GitHub
parent
70537df668
commit
3ba10e7d5b
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Breaking changes and deprecations"
|
||||
linkTitle: "Breaking changes and deprecations"
|
||||
weight: 2500
|
||||
description: "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 CRD template
|
||||
- Publicly accessible API
|
||||
- Publicly visible SDK interface, method, class, or attribute
|
||||
|
||||
Breaking changes can be applied right away to the following cases:
|
||||
|
||||
- Projects versioned at 0.x.y
|
||||
- Preview feature
|
||||
- Alpha API
|
||||
- Preview or Alpha interface, class, method or attribute in SDK
|
||||
- Dapr Component in Alpha or Beta
|
||||
- Components-Contrib interface
|
||||
- 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:
|
||||
|
||||
1. A deprecation notice must be posted as part of a release.
|
||||
1. 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 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]({{< ref kubernetes-job.md >}}) instead) | 1.2.0 | 1.4.0 |
|
||||
| Java domain builder classes deprecated (Users should use [setters](https://github.com/dapr/java-sdk/issues/587) 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]({{< ref "service_invocation_api.md#request-contents" >}}) 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 ]({{< ref howto-invoke-services-grpc.md >}}) to use the proxy mode.| 1.9.0 | 1.10.0 |
|
||||
|
||||
## Related links
|
||||
|
||||
- Read the [Versioning Policy]({{< ref support-versioning.md >}})
|
||||
- Read the [Supported Releases]({{< ref support-release-policy.md >}})
|
||||
|
|
@ -28,6 +28,17 @@ There will be at least 6 weeks between major.minor version releases giving users
|
|||
|
||||
Patch support is for supported versions (current and previous).
|
||||
|
||||
## Build variations
|
||||
|
||||
The Dapr's sidecar image is published to both [GitHub Container Registry](https://github.com/dapr/dapr/pkgs/container/daprd) and [Docker Registry](https://hub.docker.com/r/daprio/daprd/tags). The default image contains all components. From version 1.11, Dapr also offers a variation of the sidecar image, containing only stable components.
|
||||
|
||||
* Default sidecar images: `daprio/daprd:<version>` or `ghcr.io/dapr/daprd:<version>` (for example `ghcr.io/dapr/daprd:1.11.0`)
|
||||
* Sidecar images for stable components: `daprio/daprd:<version>-stable` or `ghcr.io/dapr/daprd:<version>-stable` (for example `ghcr.io/dapr/daprd:1.11.0-stable`)
|
||||
|
||||
On Kubernetes, the sidecar image can be overwritten for the application Deployment resource with the `dapr.io/sidecar-image` annotation. See more about [Dapr's arguments and annotations]({{<ref "arguments-annotations-overview.md" >}}). The default 'daprio/daprd:latest' image is used if not specified.
|
||||
|
||||
Learn more about [Dapr components' certification lifecycle]({{<ref "certification-lifecycle.md" >}}).
|
||||
|
||||
## Supported versions
|
||||
|
||||
The table below shows the versions of Dapr releases that have been tested together and form a "packaged" release. Any other combinations of releases are not supported.
|
||||
|
|
@ -106,59 +117,6 @@ General guidance on upgrading can be found for [self hosted mode]({{< ref self-h
|
|||
| 1.9.0 | N/A | 1.9.6 |
|
||||
| 1.10.0 | N/A | 1.10.7 |
|
||||
|
||||
## 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 CRD template
|
||||
- Publicly accessible API
|
||||
- Publicly visible SDK interface, method, class, or attribute
|
||||
|
||||
Breaking changes can be applied right away to the following cases:
|
||||
|
||||
- Projects versioned at 0.x.y
|
||||
- Preview feature
|
||||
- Alpha API
|
||||
- Preview or Alpha interface, class, method or attribute in SDK
|
||||
- Dapr Component in Alpha or Beta
|
||||
- Components-Contrib interface
|
||||
- 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:
|
||||
|
||||
1. A deprecation notice must be posted as part of a release.
|
||||
1. 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.
|
||||
|
||||
### Depreciations
|
||||
|
||||
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]({{< ref kubernetes-job.md >}}) instead) | 1.2.0 | 1.4.0 |
|
||||
| Java domain builder classes deprecated (Users should use [setters](https://github.com/dapr/java-sdk/issues/587) 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]({{< ref "service_invocation_api.md#request-contents" >}}) 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 ]({{< ref howto-invoke-services-grpc.md >}}) to use the proxy mode.| 1.9.0 | 1.10.0 |
|
||||
|
||||
## Upgrade on Hosting platforms
|
||||
|
||||
Dapr can support multiple hosting platforms for production. With the 1.0 release the two supported platforms are Kubernetes and physical machines. For Kubernetes upgrades see [Production guidelines on Kubernetes]({{< ref kubernetes-production.md >}})
|
||||
|
|
@ -175,4 +133,5 @@ Below is a list of software that the latest version of Dapr (v{{% dapr-latest-ve
|
|||
|
||||
## Related links
|
||||
|
||||
- Read the [Versioning policy]({{< ref support-versioning.md >}})
|
||||
- Read the [Versioning Policy]({{< ref support-versioning.md >}})
|
||||
- Read the [Breaking Changes and Deprecation Policy]({{< ref breaking-changes-and-deprecations.md >}})
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ This table is meant to help users understand the equivalent options for running
|
|||
| `--dapr-http-port` | `--dapr-http-port` | | not supported | The HTTP port for the Dapr API |
|
||||
| `--dapr-http-max-request-size` | --dapr-http-max-request-size | | `dapr.io/http-max-request-size` | Increasing max size of request body http and grpc servers parameter in MB to handle uploading of big files. Default is `4` MB |
|
||||
| `--dapr-http-read-buffer-size` | --dapr-http-read-buffer-size | | `dapr.io/http-read-buffer-size` | Increasing max size of http header read buffer in KB to handle when sending multi-KB headers. The default 4 KB. When sending bigger than default 4KB http headers, you should set this to a larger value, for example 16 (for 16KB) |
|
||||
| not supported | `--image` | | `dapr.io/sidecar-image` | Dapr sidecar image. Default is `daprio/daprd:latest`. Use this when building your own custom image of Dapr and the Dapr sidecar will use this image instead of the default image of Dapr |
|
||||
| not supported | `--image` | | `dapr.io/sidecar-image` | Dapr sidecar image. Default is daprio/daprd:latest. The Dapr sidecar uses this image instead of the latest default image. Use this when building your own custom image of Dapr and or [using an alternative stable Dapr image]({{<ref "support-release-policy.md#build-variations" >}}) |
|
||||
| `--internal-grpc-port` | not supported | | not supported | gRPC port for the Dapr Internal API to listen on |
|
||||
| `--enable-metrics` | not supported | | configuration spec | Enable prometheus metric (default true) |
|
||||
| `--enable-mtls` | not supported | | configuration spec | Enables automatic mTLS for daprd to daprd communication channels |
|
||||
|
|
|
|||
Loading…
Reference in New Issue