Add release notes

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[]

docs/release-notes.asciidoc

@@ -0,0 +1,9 @@
+[[release_notes]]
+== Release notes
+
+* <<breaking-changes-policy>>
+* <<release_notes_7_17>>
+
+include::release-notes/breaking-change-policy.asciidoc[]
+include::release-notes/7.17.asciidoc[]
+

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 <<breaking-changes-policy>>. 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}

docs/release-notes/breaking-change-policy.asciidoc

@@ -0,0 +1,26 @@
+[[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
+
+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.
+
+[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 or new developments.