Breaking changes policy

The Elasticsearch .NET Client source code is generated from a formal specification of the Elasticsearch API. This API specification is large, and although it is tested against hundreds of Elasticsearch test files, it may have discrepancies with the actual API that result in issues in the Elasticsearch .NET Client.

Fixing these discrepancies in the API specification results in code changes in the Elasticsearch .NET Client, and some of these changes can require code updates in your applications.

This section explains how these breaking changes are considered for inclusion in Elasticsearch .NET Client releases.

Some issues in the API specification are properties that have an incorrect type, such as a long that should be a string, or a required property that is actually optional. These issues can cause the Elasticsearch .NET Client to not work properly or even throw exceptions.

When a specification issue is discovered and resolved, it may require code updates in applications using the Elasticsearch .NET Client. Such breaking changes are considered acceptable, even in patch releases (e.g. 8.0.0 → 8.0.1), as they introduce stability to APIs that may otherwise be unusable.

We may also make breaking changes in patch releases to correct design flaws and code-generation issues that we deem beneficial to resolve at the earliest oppotunity. We will detail these in the relevant release notes and limit these as the client matures.

Along with these bug fixes, the API specification is constantly refined, more precise type definitions are introduced to improve developer comfort and remove ambiguities. The specification of often-used APIs is fairly mature, so these changes happen generally on less often used APIs. These changes can also cause breaking changes requiring code updates which are considered acceptable in minor releases (e.g. 8.0 → 8.1).

Major releases (e.g. 7.x → 8.x) can include larger refactorings of the API specification and the framework underlying the Elasticsearch .NET Client. These refactorings are considered carefully and done only when they unlock new important features or new developments.

All Elasticsearch APIs have stability indicators, which imply potential changes. If an API is stable only additional non-breaking changes are added. In case of experimental APIs, breaking changes can be introduced any time, which means that these changes, will also be reflected in the Elasticsearch .NET Client.