From b8321963ecfd46d52ccf16d84da1db9fa3c44356 Mon Sep 17 00:00:00 2001 From: Sylvain Wallez Date: Fri, 11 Feb 2022 18:59:00 +0100 Subject: [PATCH 1/4] Add release notes --- docs/index.asciidoc | 1 + docs/release-notes.asciidoc | 9 + docs/release-notes/7.17.asciidoc | 262 ++++++++++++++++++ .../breaking-change-policy.asciidoc | 19 ++ 4 files changed, 291 insertions(+) create mode 100644 docs/release-notes.asciidoc create mode 100644 docs/release-notes/7.17.asciidoc create mode 100644 docs/release-notes/breaking-change-policy.asciidoc diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 71775d8bf..1515c5835 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -26,5 +26,6 @@ include::connecting.asciidoc[] include::migrate.asciidoc[] include::api-conventions.asciidoc[] include::javadoc-and-source.asciidoc[] +include::release-notes.asciidoc[] include::{elasticsearch-root}/docs/java-rest/low-level/index.asciidoc[] diff --git a/docs/release-notes.asciidoc b/docs/release-notes.asciidoc new file mode 100644 index 000000000..56600a111 --- /dev/null +++ b/docs/release-notes.asciidoc @@ -0,0 +1,9 @@ +[[release_notes]] +== Release notes + +* <> +* <> + +include::release-notes/breaking-change-policy.asciidoc[] +include::release-notes/7.17.asciidoc[] + diff --git a/docs/release-notes/7.17.asciidoc b/docs/release-notes/7.17.asciidoc new file mode 100644 index 000000000..58024f467 --- /dev/null +++ b/docs/release-notes/7.17.asciidoc @@ -0,0 +1,262 @@ +[[release_notes_7_17]] +=== Version 7.17 + +[discrete] +==== Changes and bug fixes + +This release includes minor updates and improvement to the API specification and a number of bug fixes (see closed issues in the https://github.com/elastic/elasticsearch-java/milestone/1?closed=1[GitHub repo]). + +[discrete] +==== Breaking changes between 7.16 and 7.17 + +Please refer to the <>. The `co.elastic.clients.elasticsearch` package is abbreviated to `c.e.c.e` below. + +An issue in the code generator led properties whose API name contains a dot (`.`) to be removed. They will be reintroduced in version 7.17.1: + +Class `c.e.c.e._types.aggregations.ChildrenAggregate`: :: +* Parent class changed from `c.e.c.e._types.aggregations.MultiBucketAggregateBase` to `c.e.c.e._types.aggregations.SingleBucketAggregateBase`. +Class `c.e.c.e._types.aggregations.ChildrenAggregateBucket` removed.:: +Class `c.e.c.e._types.aggregations.StringStatsAggregate`: :: +* Property `distribution` changed from `String` to `Map`. +Class `c.e.c.e._types.aggregations.TopMetricsAggregate`: :: +* Parent class changed from `c.e.c.e._types.aggregations.MultiBucketAggregateBase` to `c.e.c.e._types.aggregations.AggregateBase`. +Class `c.e.c.e._types.aggregations.TopMetricsBucket` removed.:: +Class `c.e.c.e._types.ChainTransform` removed.:: +Class `c.e.c.e._types.DocStats`: :: +* Property `deleted` changed from `long` to `Long`. +Class `c.e.c.e._types.EmptyTransform` removed.:: +Class `c.e.c.e._types.query_dsl.CombinedFieldsQuery`: :: +* Property `mimimumShouldMatch` removed. +Class `c.e.c.e._types.query_dsl.RangeQuery`: :: +* Property `from` changed from `c.e.c.json.JsonData` to `String`. +* Property `to` changed from `c.e.c.json.JsonData` to `String`. +Class `c.e.c.e._types.SegmentsStats`: :: +* Property `maxUnsafeAutoIdTimestamp` changed from `int` to `long`. +Class `c.e.c.e._types.Transform`: :: +* Property `chain` changed from `c.e.c.e._types.ChainTransform` to `List`. +Class `c.e.c.e.cat.indices.IndicesRecord`: :: +* Property `priBulkAvgSizeInBytes` removed. +* Property `priBulkAvgTime` removed. +* Property `priBulkTotalOperations` removed. +* Property `priBulkTotalSizeInBytes` removed. +* Property `priBulkTotalTime` removed. +* Property `priCompletionSize` removed. +* Property `priFielddataEvictions` removed. +* Property `priFielddataMemorySize` removed. +* Property `priFlushTotal` removed. +* Property `priFlushTotalTime` removed. +* Property `priGetCurrent` removed. +* Property `priGetExistsTime` removed. +* Property `priGetExistsTotal` removed. +* Property `priGetMissingTime` removed. +* Property `priGetMissingTotal` removed. +* Property `priGetTime` removed. +* Property `priGetTotal` removed. +* Property `priIndexingDeleteCurrent` removed. +* Property `priIndexingDeleteTime` removed. +* Property `priIndexingDeleteTotal` removed. +* Property `priIndexingIndexCurrent` removed. +* Property `priIndexingIndexFailed` removed. +* Property `priIndexingIndexTime` removed. +* Property `priIndexingIndexTotal` removed. +* Property `priMemoryTotal` removed. +* Property `priMergesCurrent` removed. +* Property `priMergesCurrentDocs` removed. +* Property `priMergesCurrentSize` removed. +* Property `priMergesTotal` removed. +* Property `priMergesTotalDocs` removed. +* Property `priMergesTotalSize` removed. +* Property `priMergesTotalTime` removed. +* Property `priQueryCacheEvictions` removed. +* Property `priQueryCacheMemorySize` removed. +* Property `priRefreshExternalTime` removed. +* Property `priRefreshExternalTotal` removed. +* Property `priRefreshListeners` removed. +* Property `priRefreshTime` removed. +* Property `priRefreshTotal` removed. +* Property `priRequestCacheEvictions` removed. +* Property `priRequestCacheHitCount` removed. +* Property `priRequestCacheMemorySize` removed. +* Property `priRequestCacheMissCount` removed. +* Property `priSearchFetchCurrent` removed. +* Property `priSearchFetchTime` removed. +* Property `priSearchFetchTotal` removed. +* Property `priSearchOpenContexts` removed. +* Property `priSearchQueryCurrent` removed. +* Property `priSearchQueryTime` removed. +* Property `priSearchQueryTotal` removed. +* Property `priSearchScrollCurrent` removed. +* Property `priSearchScrollTime` removed. +* Property `priSearchScrollTotal` removed. +* Property `priSegmentsCount` removed. +* Property `priSegmentsFixedBitsetMemory` removed. +* Property `priSegmentsIndexWriterMemory` removed. +* Property `priSegmentsMemory` removed. +* Property `priSegmentsVersionMapMemory` removed. +* Property `priStoreSize` removed. +* Property `priSuggestCurrent` removed. +* Property `priSuggestTime` removed. +* Property `priSuggestTotal` removed. +* Property `priWarmerCurrent` removed. +* Property `priWarmerTotal` removed. +* Property `priWarmerTotalTime` removed. +Class `c.e.c.e.cat.nodes.NodesRecord`: :: +* Property `refreshTime` removed. +* Property `refreshTotal` removed. +Class `c.e.c.e.cat.shards.ShardsRecord`: :: +* Property `refreshTime` removed. +* Property `refreshTotal` removed. +Class `c.e.c.e.core.bulk.UpdateOperation`: :: +* Property `document` removed. +Class `c.e.c.e.core.DeleteByQueryRequest`: :: +* Property `source` removed. +* Property `sourceExcludes` removed. +* Property `sourceIncludes` removed. +Class `c.e.c.e.core.msearch.MultiSearchItem`: :: +* Property `status` changed from `int` to `Integer`. +Class `c.e.c.e.core.search.CompletionSuggestOption`: :: +* Property `score` changed from `double` to `Double`. +Class `c.e.c.e.core.search.Suggestion`: :: +* Property `length` removed. +* Property `offset` removed. +* Property `options` removed. +* Property `serializeInternal` removed. +* Property `setupSuggestionDeserializer` removed. +* Property `text` removed. +Class `c.e.c.e.core.search.SuggestOption` removed.:: +Class `c.e.c.e.core.search.TermSuggestOption`: :: +* Property `freq` changed from `Long` to `long`. +Class `c.e.c.e.core.SearchTemplateResponse`: :: +* Property `took` changed from `int` to `long`. +Class `c.e.c.e.core.UpdateByQueryRequest`: :: +* Property `source` removed. +* Property `sourceExcludes` removed. +* Property `sourceIncludes` removed. +Class `c.e.c.e.indices.data_streams_stats.DataStreamsStatsItem`: :: +* Property `maximumTimestamp` changed from `int` to `long`. +Class `c.e.c.e.indices.stats.IndexStats`: :: +* Property `shards` removed. +Class `c.e.c.e.logstash.PipelineSettings`: :: +* Property `pipelineBatchDelay` removed. +* Property `pipelineBatchSize` removed. +* Property `pipelineWorkers` removed. +* Property `queueCheckpointWrites` removed. +* Property `queueMaxBytesNumber` removed. +* Property `queueMaxBytesUnits` removed. +* Property `queueType` removed. +Class `c.e.c.e.ml.DataCounts`: :: +* Property `earliestRecordTimestamp` changed from `long` to `Long`. +* Property `lastDataTime` changed from `long` to `Long`. +* Property `latestBucketTimestamp` changed from `long` to `Long`. +* Property `latestEmptyBucketTimestamp` changed from `long` to `Long`. +* Property `latestRecordTimestamp` changed from `long` to `Long`. +* Property `latestSparseBucketTimestamp` changed from `long` to `Long`. +Class `c.e.c.e.ml.Job`: :: +* Property `createTime` changed from `int` to `Integer`. +Class `c.e.c.e.ml.JobTimingStats`: :: +* Property `averageBucketProcessingTimeMs` changed from `double` to `Double`. +* Property `exponentialAverageBucketProcessingTimeMs` changed from `double` to `Double`. +* Property `maximumBucketProcessingTimeMs` changed from `double` to `Double`. +* Property `minimumBucketProcessingTimeMs` changed from `double` to `Double`. +Class `c.e.c.e.ml.ModelSnapshot`: :: +* Property `timestamp` changed from `int` to `long`. +Class `c.e.c.e.ml.PostDataResponse`: :: +* Property `earliestRecordTimestamp` changed from `int` to `long`. +* Property `latestRecordTimestamp` changed from `int` to `long`. +Class `c.e.c.e.nodes.AdaptiveSelection`: :: +* Property `avgQueueSize` changed from `long` to `Long`. +* Property `avgResponseTime` changed from `long` to `Long`. +* Property `avgResponseTimeNs` changed from `long` to `Long`. +* Property `avgServiceTimeNs` changed from `long` to `Long`. +* Property `outgoingSearches` changed from `long` to `Long`. +Class `c.e.c.e.nodes.Breaker`: :: +* Property `estimatedSizeInBytes` changed from `long` to `Long`. +* Property `limitSizeInBytes` changed from `long` to `Long`. +* Property `overhead` changed from `float` to `Float`. +* Property `tripped` changed from `float` to `Float`. +Class `c.e.c.e.nodes.Cpu`: :: +* Property `percent` changed from `int` to `Integer`. +Class `c.e.c.e.nodes.DataPathStats`: :: +* Property `availableInBytes` changed from `long` to `Long`. +* Property `diskReads` changed from `long` to `Long`. +* Property `diskReadSizeInBytes` changed from `long` to `Long`. +* Property `diskWrites` changed from `long` to `Long`. +* Property `diskWriteSizeInBytes` changed from `long` to `Long`. +* Property `freeInBytes` changed from `long` to `Long`. +* Property `totalInBytes` changed from `long` to `Long`. +Class `c.e.c.e.nodes.ExtendedMemoryStats`: :: +* Property `freePercent` changed from `int` to `Integer`. +* Property `usedPercent` changed from `int` to `Integer`. +Class `c.e.c.e.nodes.FileSystem`: :: +* Property `timestamp` changed from `long` to `Long`. +Class `c.e.c.e.nodes.FileSystemTotal`: :: +* Property `availableInBytes` changed from `long` to `Long`. +* Property `freeInBytes` changed from `long` to `Long`. +* Property `totalInBytes` changed from `long` to `Long`. +Class `c.e.c.e.nodes.GarbageCollectorTotal`: :: +* Property `collectionCount` changed from `long` to `Long`. +* Property `collectionTimeInMillis` changed from `long` to `Long`. +Class `c.e.c.e.nodes.Http`: :: +* Property `currentOpen` changed from `int` to `Integer`. +* Property `totalOpened` changed from `long` to `Long`. +Class `c.e.c.e.nodes.info.NodeInfoSettingsHttp`: :: +* Property `typeDefault` removed. +Class `c.e.c.e.nodes.info.NodeInfoSettingsTransport`: :: +* Property `typeDefault` removed. +Class `c.e.c.e.nodes.IngestTotal`: :: +* Property `count` changed from `long` to `Long`. +* Property `current` changed from `long` to `Long`. +* Property `failed` changed from `long` to `Long`. +* Property `timeInMillis` changed from `long` to `Long`. +Class `c.e.c.e.nodes.Jvm`: :: +* Property `mem` changed from `c.e.c.e.nodes.MemoryStats` to `c.e.c.e.nodes.JvmMemoryStats`. +* Property `timestamp` changed from `long` to `Long`. +* Property `uptimeInMillis` changed from `long` to `Long`. +Class `c.e.c.e.nodes.JvmClasses`: :: +* Property `currentLoadedCount` changed from `long` to `Long`. +* Property `totalLoadedCount` changed from `long` to `Long`. +* Property `totalUnloadedCount` changed from `long` to `Long`. +Class `c.e.c.e.nodes.JvmThreads`: :: +* Property `count` changed from `long` to `Long`. +* Property `peakCount` changed from `long` to `Long`. +Class `c.e.c.e.nodes.KeyedProcessor`: :: +* Property `statistics` removed. +Class `c.e.c.e.nodes.MemoryStats`: :: +* Property `freeInBytes` changed from `long` to `Long`. +* Property `totalInBytes` changed from `long` to `Long`. +* Property `usedInBytes` changed from `long` to `Long`. +Class `c.e.c.e.nodes.NodeBufferPool`: :: +* Property `count` changed from `long` to `Long`. +* Property `totalCapacityInBytes` changed from `long` to `Long`. +* Property `usedInBytes` changed from `long` to `Long`. +Class `c.e.c.e.nodes.OperatingSystem`: :: +* Property `timestamp` changed from `long` to `Long`. +Class `c.e.c.e.nodes.Process`: :: +* Property `openFileDescriptors` changed from `int` to `Integer`. +* Property `timestamp` changed from `long` to `Long`. +Class `c.e.c.e.nodes.Scripting`: :: +* Property `cacheEvictions` changed from `long` to `Long`. +* Property `compilations` changed from `long` to `Long`. +Class `c.e.c.e.nodes.Stats`: :: +* Property `indices` changed from `c.e.c.e.indices.stats.IndexStats` to `c.e.c.e.indices.stats.ShardStats`. +* Property `timestamp` changed from `long` to `Long`. +Class `c.e.c.e.nodes.ThreadCount`: :: +* Property `active` changed from `long` to `Long`. +* Property `completed` changed from `long` to `Long`. +* Property `largest` changed from `long` to `Long`. +* Property `queue` changed from `long` to `Long`. +* Property `rejected` changed from `long` to `Long`. +* Property `threads` changed from `long` to `Long`. +Class `c.e.c.e.nodes.Transport`: :: +* Property `rxCount` changed from `long` to `Long`. +* Property `rxSizeInBytes` changed from `long` to `Long`. +* Property `serverOpen` changed from `int` to `Integer`. +* Property `txCount` changed from `long` to `Long`. +* Property `txSizeInBytes` changed from `long` to `Long`. +Class `c.e.c.e.transform.GetTransformStatsRequest`: :: +* Property `transformId` changed from `String` to `List`. +Class `c.e.c.e.watcher.CompareCondition`: :: +* Property `ctxPayloadMatch` removed. +* Property `ctxPayloadValue` removed. +Class `c.e.c.e.watcher.CompareContextPayloadCondition` removed.:: +{nbsp} diff --git a/docs/release-notes/breaking-change-policy.asciidoc b/docs/release-notes/breaking-change-policy.asciidoc new file mode 100644 index 000000000..a98e82f5b --- /dev/null +++ b/docs/release-notes/breaking-change-policy.asciidoc @@ -0,0 +1,19 @@ +[[breaking-changes-policy]] +=== Breaking changes policy + +[discrete] +==== Breaking changes in patch releases + +The Elasticsearch API used to produce the {java-client} is large and can have issues in how types are defined. These can result in issues causing the {java-client} to not work properly or even throw exceptions (e.g. when an optional property was labelled as required). + +When these specification issues are found and fixed, they can result in breaking changes in the Java client, requiring code updates. These are considered acceptable, _even in patch releases_ (e.g. 7.17.0 -> 7.17.1), as they fix issues in the {java-client} that would otherwise make the corresponding APIs unusable. + +[discrete] +==== Breaking changes in minor releases + +Along with these bug fixes, the API specification is constantly refined and 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). + +[discrete] +==== Breaking changes in major releases + +Major releases (e.g. 7.x -> 8.x) can include larger refactorings of the API specification and the framework underlying the {java-client}. These refactorings are considered carefully and done only when they unlock new important features of developments. From 94cd5db4fd5629fcc02c27c333bd87af3c98cf7f Mon Sep 17 00:00:00 2001 From: Sylvain Wallez Date: Mon, 14 Feb 2022 11:17:11 +0100 Subject: [PATCH 2/4] Refine breaking change policy --- docs/release-notes/breaking-change-policy.asciidoc | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/release-notes/breaking-change-policy.asciidoc b/docs/release-notes/breaking-change-policy.asciidoc index a98e82f5b..f6e14c462 100644 --- a/docs/release-notes/breaking-change-policy.asciidoc +++ b/docs/release-notes/breaking-change-policy.asciidoc @@ -1,12 +1,19 @@ [[breaking-changes-policy]] === Breaking changes policy + +The {java-client} source code is generated from a https://github.com/elastic/elasticsearch-specification[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 {java-client}. + +Fixing these discrepancies in the API specification result in code changes in the {java-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 {java-client} releases. + [discrete] ==== Breaking changes in patch releases -The Elasticsearch API used to produce the {java-client} is large and can have issues in how types are defined. These can result in issues causing the {java-client} to not work properly or even throw exceptions (e.g. when an optional property was labelled as required). +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 {java-client} to not work properly or even throw exceptions. -When these specification issues are found and fixed, they can result in breaking changes in the Java client, requiring code updates. These are considered acceptable, _even in patch releases_ (e.g. 7.17.0 -> 7.17.1), as they fix issues in the {java-client} that would otherwise make the corresponding APIs unusable. +When these specification issues are found and fixed, they may require code updates in applications using the {java-client}. These are considered acceptable, _even in patch releases_ (e.g. 7.17.0 -> 7.17.1), as they fix issues that would otherwise make the corresponding APIs unusable. [discrete] ==== Breaking changes in minor releases @@ -16,4 +23,4 @@ Along with these bug fixes, the API specification is constantly refined and more [discrete] ==== Breaking changes in major releases -Major releases (e.g. 7.x -> 8.x) can include larger refactorings of the API specification and the framework underlying the {java-client}. These refactorings are considered carefully and done only when they unlock new important features of developments. +Major releases (e.g. 7.x -> 8.x) can include larger refactorings of the API specification and the framework underlying the {java-client}. These refactorings are considered carefully and done only when they unlock new important features or new developments. From ca756bc14933300109a29e10fbe5a89f812e6e73 Mon Sep 17 00:00:00 2001 From: Sylvain Wallez Date: Mon, 14 Feb 2022 15:14:18 +0100 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Philip Krauss <35487337+philkra@users.noreply.github.com> --- docs/release-notes/breaking-change-policy.asciidoc | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/release-notes/breaking-change-policy.asciidoc b/docs/release-notes/breaking-change-policy.asciidoc index f6e14c462..f32cb81ba 100644 --- a/docs/release-notes/breaking-change-policy.asciidoc +++ b/docs/release-notes/breaking-change-policy.asciidoc @@ -7,18 +7,21 @@ The {java-client} source code is generated from a https://github.com/elastic/ela Fixing these discrepancies in the API specification result in code changes in the {java-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 {java-client} releases. +[discrete] +==== Elasticsearch Stability Guarantees +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 {java-client}. [discrete] ==== Breaking changes in patch 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 {java-client} to not work properly or even throw exceptions. -When these specification issues are found and fixed, they may require code updates in applications using the {java-client}. These are considered acceptable, _even in patch releases_ (e.g. 7.17.0 -> 7.17.1), as they fix issues that would otherwise make the corresponding APIs unusable. +When a specification issue is discovered and resolved, it may require code update in applications using the {java-client}. These breaking changes, _even in patch releases_ (e.g. 7.17.0 -> 7.17.1), are considered acceptable as it introduces stability and otherwise the corresponding API might unusable. [discrete] ==== Breaking changes in minor releases -Along with these bug fixes, the API specification is constantly refined and 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). +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). [discrete] ==== Breaking changes in major releases From fb10de880cd8250c8e41c5af29c3ac8b8dceb1d2 Mon Sep 17 00:00:00 2001 From: Sylvain Wallez Date: Mon, 14 Feb 2022 15:44:36 +0100 Subject: [PATCH 4/4] Refine breaking change policy --- CHANGELOG.md | 1 + docs/release-notes/breaking-change-policy.asciidoc | 13 +++++++------ 2 files changed, 8 insertions(+), 6 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 000000000..a0bb469ca --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1 @@ +See the [release notes](https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/release_notes.html) sections in the main documentation. diff --git a/docs/release-notes/breaking-change-policy.asciidoc b/docs/release-notes/breaking-change-policy.asciidoc index f32cb81ba..60974e598 100644 --- a/docs/release-notes/breaking-change-policy.asciidoc +++ b/docs/release-notes/breaking-change-policy.asciidoc @@ -1,22 +1,18 @@ [[breaking-changes-policy]] === Breaking changes policy - The {java-client} source code is generated from a https://github.com/elastic/elasticsearch-specification[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 {java-client}. -Fixing these discrepancies in the API specification result in code changes in the {java-client}, and some of these changes can require code updates in your applications. +Fixing these discrepancies in the API specification results in code changes in the {java-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 {java-client} releases. -[discrete] -==== Elasticsearch Stability Guarantees -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 {java-client}. [discrete] ==== Breaking changes in patch 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 {java-client} to not work properly or even throw exceptions. -When a specification issue is discovered and resolved, it may require code update in applications using the {java-client}. These breaking changes, _even in patch releases_ (e.g. 7.17.0 -> 7.17.1), are considered acceptable as it introduces stability and otherwise the corresponding API might unusable. +When a specification issue is discovered and resolved, it may require code updates in applications using the {java-client}. Such breaking changes are considered acceptable, _even in patch releases_ (e.g. 7.17.0 -> 7.17.1), as they introduce stability to APIs that may otherwise be unusable. [discrete] ==== Breaking changes in minor releases @@ -27,3 +23,8 @@ Along with these bug fixes, the API specification is constantly refined, more pr ==== Breaking changes in major releases Major releases (e.g. 7.x -> 8.x) can include larger refactorings of the API specification and the framework underlying the {java-client}. These refactorings are considered carefully and done only when they unlock new important features or new developments. + +[discrete] +==== Elasticsearch API stability guarantees + +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 {java-client}.