Versioning policy

    Dapr is designed for future changes in the runtime, APIs and components with versioning schemes. This topic describes the versioning schemes and strategies for APIs, manifests such as components and Github repositories.

    Versioning

    Versioning is the process of assigning either unique version names or unique version numbers to unique states of computer software.

    • Versioning provides compatibility, explicit change control and handling changes, in particular breaking changes.
    • Dapr strives to be backwards compatible. If a breaking change is needed it’ll be .
    • Deprecated features are done over multiple releases with both new and deprecated features working side-by-side.

    Versioning refers to the following Dapr repos: dapr, CLI, stable language SDKs, dashboard, components-contrib, quickstarts, helm-charts and documentation.

    Dapr has the following versioning schemes:

    • Dapr versioned with MAJOR.MINOR
    • Dapr GRPC API with MAJOR
    • Releases (GitHub repositories including dapr, CLI, SDKs and Helm Chart) with MAJOR.MINOR.PATCH
    • Documentation and Quickstarts repositories are versioned with the Dapr runtime repository versioning.
    • Dapr Components with MAJOR in components-contrib GitHub repositories.

    Note that the Dapr APIs, binaries releases (runtime, CLI, SDKs) and components are all independent from one another.

    Dapr HTTP API

    The Dapr HTTP API is versioned according to these .

    Based to the these guidelines;

    • A MAJOR version of the API is incremented when a deprecation is expected of the older version. Any such deprecation will be communicated and an upgrade path made available.
    • A MINOR versions may be incremented for any other changes. For example a change to the JSON schema of the message sent to the API. The definition of a breaking change to the API can be viewed here.
    • Experimental APIs include an “alpha” suffix to denote for their alpha status. For example v1.0alpha, v2.0alpha, etc.

    Helm Charts

    Helm charts in the helm-charts repo are versioned with the Dapr runtime. The Helm charts are used in the

    Language SDKs, CLI and dashboard

    The Dapr language SDKs, CLI and dashboard are versioned independently from the Dapr runtime and can be released at different schedules. See this to show the compatibility between versions of the SDKs, CLI, dashboard and runtime. Each new release on the runtime lists the corresponding supported SDKs, CLI and Dashboard.

    SDKs, CLIs and Dashboard are versioning follows a MAJOR.MINOR.PATCH format. A major version is incremented when there’s a non-backwards compatible change in an SDK (for example, changing a parameter on a client method. A minor version is updated for new features and bug fixes and the patch version is incremented in case of bug or security hot fixes.

    Samples and examples in SDKs version with that repo.

    Components are implemented in the components-contrib repository and follow a MAJOR versioning scheme. The version for components adheres to major versions (vX), as patches and non-breaking changes are added to the latest major version. The version is incremented when there’s a non-backwards compatible change in a component interface, for example, changing an existing method in the State Store interface.

    The components-contrib repo release is a flat version across all components inside. That is, a version for the components-contrib repo release is made up of all the schemas for the components inside it. A new version of Dapr does not mean there is a new release of components-contrib if there are no component changes.

    Note: Components have a production usage lifecycle status: Alpha, Beta and GA (stable). These statuses are not related to their versioning. The tables of supported components shows both their versions and their status.

    Versioning for component YAMLs comes in two forms:

    • Versioning for the component manifest. The
    • Version for the component implementation. The .spec.version

    A component manifest includes the schema for an implementation in the .spec.metadata field, with the .type field denoting the implementation

    See the comments in the example below:

    The Component YAML manifest is versioned with dapr.io/v1alpha1.

    The version for a component implementation is determined by the .spec.version field as can be seen in the example above. The .spec.version field is mandatory in a schema instance and the component fails to load if this is not present. For the release of Dapr 1.0.0 all components are marked as .The component implementation version is incremented only for non-backward compatible changes.

    Deprecations of components will be announced two (2) releases ahead. Deprecation of a component, results in major version update of the component version. After 2 releases, the component is unregistered from the Dapr runtime, and trying to load it will throw a fatal exception.

    Quickstarts and Samples

    Quickstarts in the Quickstarts repo are versioned with the runtime, where a table of corresponding versions is on the front page of the samples repo. Users should only use Quickstarts corresponding to the version of the runtime being run.