From 896fa4d75e5889a1e4a3668b6a6c3b137fe614e4 Mon Sep 17 00:00:00 2001 From: Thomas Farr Date: Wed, 24 Apr 2024 12:25:20 +1200 Subject: [PATCH] Add UPGRADING.md to document breaking changes (#618) * Add UPGRADING.md to document breaking changes Signed-off-by: Thomas Farr * Add link in README and add TOC Signed-off-by: Thomas Farr --------- Signed-off-by: Thomas Farr --- .github/bump-version.sh | 4 +- CHANGELOG.md | 7 +- OpenSearch.sln | 1 + README.md | 6 ++ UPGRADING.md | 139 ++++++++++++++++++++++++++++++++++++++++ global.json | 2 +- 6 files changed, 155 insertions(+), 4 deletions(-) create mode 100644 UPGRADING.md diff --git a/.github/bump-version.sh b/.github/bump-version.sh index c770910145..54e548ee04 100644 --- a/.github/bump-version.sh +++ b/.github/bump-version.sh @@ -28,4 +28,6 @@ GLOBAL_JSON=$(jq \ global.json) echo "$GLOBAL_JSON" > global.json -sed -i'' -E "s/<(Current(Assembly(File)?)?Version)>([0-9]+\.){2}[0-9]+<\/\1>/<\1>$VERSION<\/\1>/" Directory.Build.props +gsed -i'' -E "s/<(Current(Assembly(File)?)?Version)>[0-9]+\.[0-9]+\.[0-9]+<\/\1>/<\1>$VERSION<\/\1>/" Directory.Build.props + +gsed -i'' -E "s/(next release of opensearch\-net, which should be \*\*)[0-9]+\.[0-9]+\.[0-9]+(\*\*\.)/\1$VERSION\2/" README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index d5d985693f..5a4c725220 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,18 +3,21 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) ## [Unreleased] ### ⚠️ Breaking Changes ⚠️ -- Removed support for the `net461` target ([#256](https://github.com/opensearch-project/opensearch-net/pull/256)) -- Fixed naming of `ClusterManagerTimeout` and `MasterTimeout` properties from `*TimeSpanout` in the low-level client ([#332](https://github.com/opensearch-project/opensearch-net/pull/332)) +As part of [efforts to re-generate the client](https://github.com/opensearch-project/opensearch-net/pulls?q=is%3Apr+label%3Acode-gen+is%3Aclosed) from our [OpenAPI specification](https://github.com/opensearch-project/opensearch-api-specification) there have been numerous corrections and changes that resulted in breaking changes. Please refer to [UPGRADING.md](UPGRADING.md) for a complete list of these breakages and any relevant guidance for upgrading to this version of the client. ### Added - Added support for the `Cat.PitSegments` and `Cat.SegmentReplication` APIs ([#527](https://github.com/opensearch-project/opensearch-net/pull/527)) ### Removed +- Removed support for the `net461` target ([#256](https://github.com/opensearch-project/opensearch-net/pull/256)) - Removed the `Features` API which is not supported by OpenSearch from the low-level client ([#331](https://github.com/opensearch-project/opensearch-net/pull/331)) - Removed the deprecated low-level `IndexTemplateV2` APIs in favour of the `ComposableIndexTemplate` APIs ([#437](https://github.com/opensearch-project/opensearch-net/pull/437)) ### Dependencies - Bumps `AWSSDK.Core` from 3.7.204.12 to 3.7.303.18 +### Fixed +- Fixed naming of `ClusterManagerTimeout` and `MasterTimeout` properties from `*TimeSpanout` in the low-level client ([#332](https://github.com/opensearch-project/opensearch-net/pull/332)) + ## [1.7.1] ### Fixed - Fixed the deserialization of S3 snapshot repositories without settings ([#587](https://github.com/opensearch-project/opensearch-net/pull/587)) diff --git a/OpenSearch.sln b/OpenSearch.sln index de0aba5da9..23ee5a2c52 100644 --- a/OpenSearch.sln +++ b/OpenSearch.sln @@ -52,6 +52,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Markdown", "Markdown", "{2F releasing.md = releasing.md security.md = security.md user_guide.md = user_guide.md + UPGRADING.md = UPGRADING.md EndProjectSection EndProject Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "Tests.YamlRunner", "tests\Tests.YamlRunner\Tests.YamlRunner.fsproj", "{81473437-5722-4829-A5CD-125B17CCA238}" diff --git a/README.md b/README.md index d300411218..81357c0ca8 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ - [OpenSearch .NET Client](#opensearch-net-client) - [Welcome!](#welcome) + - [Stable Release](#stable-release) - [Project Resources](#project-resources) - [OpenSearch.Client](#opensearch-client) - [Getting Started](#getting-started) @@ -24,6 +25,11 @@ **OpenSearch.Client** is [a community-driven, open source fork](https://aws.amazon.com/blogs/opensource/introducing-opensearch/) of elasticsearch-net high level client NEST licensed under the [Apache v2.0 License](LICENSE.txt). For more information, see [opensearch.org](https://opensearch.org/). +## Stable Release +You're reading the documentation for the next release of opensearch-net, which should be **2.0.0**. +Please read [UPGRADING](UPGRADING.md) when upgrading from a previous version. +The current stable release is [1.7.1](https://github.com/opensearch-project/opensearch-net/blob/v1.7.1/README.md). + ## Project Resources * [Project Website](https://opensearch.org/) diff --git a/UPGRADING.md b/UPGRADING.md new file mode 100644 index 0000000000..bba5b668be --- /dev/null +++ b/UPGRADING.md @@ -0,0 +1,139 @@ + +* [Upgrading OpenSearch.Net & OpenSearch.Client](#upgrading-opensearchnet--opensearchclient) + * [1.x.y to 2.0.0](#1xy-to-200) + * [OpenSearch.Net](#opensearchnet) + * [General](#general) + * [Cat.Indices Action](#catindices-action) + * [Cat.Master Action](#catmaster-action) + * [Cat.Plugins Action](#catplugins-action) + * [Cat.Recovery Action](#catrecovery-action) + * [Cluster.ExistsComponentTemplate Action](#clusterexistscomponenttemplate-action) + * [Cluster.Health Action](#clusterhealth-action) + * [Cluster.PostVotingConfigExclusions Action](#clusterpostvotingconfigexclusions-action) + * [Features Namespace](#features-namespace) + * [Indices.DeleteTemplateV2 Action](#indicesdeletetemplatev2-action) + * [Indices.ExistsTemplate Action](#indicesexiststemplate-action) + * [Indices.GetTemplateV2 Action](#indicesgettemplatev2-action) + * [Indices.PutTemplateV2 Action](#indicesputtemplatev2-action) + * [Nodes.HotThreads Action](#nodeshotthreads-action) + * [Nodes.Stats Action](#nodesstats-action) + * [Snapshot.CleanupRepository Action](#snapshotcleanuprepository-action) + * [Tasks.List Action](#taskslist-action) + * [OpenSearch.Client](#opensearchclient) + * [General](#general-1) + * [Cat.Indices Action](#catindices-action-1) + * [Cat.Master Action](#catmaster-action-1) + * [Cat.Plugins Action](#catplugins-action-1) + * [Cluster.GetComponentTemplate Action](#clustergetcomponenttemplate-action) + * [Cluster.Health Action](#clusterhealth-action-1) + * [Cluster.PostVotingConfigExclusions Action](#clusterpostvotingconfigexclusions-action-1) + * [Cluster.Stats Action](#clusterstats-action) + * [Indices.GetComposableTemplate Action](#indicesgetcomposabletemplate-action) + * [Nodes.HotThreads Action](#nodeshotthreads-action-1) + * [Nodes.Stats Action](#nodesstats-action-1) + * [Tasks.List Action](#taskslist-action-1) + + +# Upgrading OpenSearch.Net & OpenSearch.Client + +## 1.x.y to 2.0.0 + +### OpenSearch.Net + +#### General +- Support for .NET Framework v4.6.1 has been removed, if you have a .NET Framework based project it is recommended to upgrade the project to target .NET Framework v4.7.2 or higher. +- The `MasterTimeSpanout` & `ClusterManagerTimeSpanout` parameters on all actions have been corrected to `MasterTimeout` and `ClusterManagerTimeout` respectively. +- The `MasterTimeout` parameters on all actions have been marked `[Obsolete]`, please migrate to using `ClusterManagerTimeout` if your OpenSearch cluster is at least version `2.0.0` as `MasterTimeout` may be removed in future major versions. +- The `ExpandWildcards` enum is now attributed with `[Flags]` to allow combining of multiple values e.g. `ExpandWildcards.Open | ExpandWildcards.Closed` to match open and closed indexes but not hidden. + +#### Cat.Indices Action +- The `Health` parameter now accepts a new `HealthStatus` enum instead of the `Health` enum. The values are identical and are now unified with other parts of the API that utilize the same enum. + +#### Cat.Master Action +- The action has been marked `[Obsolete]`, please migrate to using `Cat.ClusterManager` if your OpenSearch cluster is at least version 2.0.0 as `Cat.Master` may be removed in future major versions. + +#### Cat.Plugins Action +- The `IncludeBootstrap` parameter has been removed as it was never supported by OpenSearch. + +#### Cat.Recovery Action +- The `IndexQueryString` parameter has been renamed to simply `Index` + +#### Cluster.ExistsComponentTemplate Action +- This action has been removed in favour of the correctly named `Cluster.ComponentTemplateExists` action. + +#### Cluster.Health Action +- The `Level` parameter now accepts a new `ClusterHealthLevel` enum instead of the `Level` enum. The values are the same except for the addition of the `AwarenessAttributes` value. +- The `WaitForStatus` parameter now accepts a new `HealthStatus` enum instead of the `WaitForStatus` enum. The values are identical and are now unified with other parts of the API that utilize the same enum. + +#### Cluster.PostVotingConfigExclusions Action +- The `NodeIds` & `NodeNames` parameters now accept an array of strings instead of a single string to better represent the underlying API that accepts comma-separated lists. + +#### Features Namespace +- The entire `Features` API namespace has been removed, there is no migration path as it was never supported by OpenSearch. + +#### Indices.DeleteTemplateV2 Action +- This action has been removed in favour of the more descriptively named and typed `Indices.DeleteComposableTemplate` action. + +#### Indices.ExistsTemplate Action +- This action has been removed due to confusing naming as it in the prior naming scheme it should have been `TemplateExistsV2` because it should be used with composable index templates, however it could be confused with the legacy `TemplateExists` action. Please migrate to the correct action depending on your use case: + - `Indices.TemplateExists` for legacy index templates, i.e. the `/_template/{name}` API. + - `Indices.ComposableTemplateExists` for newer composable index templates, i.e. the `/_index_template/{name}` API. + +#### Indices.GetTemplateV2 Action +- This action has been removed in favour of the more descriptively named and typed `Indices.GetComposableTemplate` action. + +#### Indices.PutTemplateV2 Action +- This action has been removed in favour of the more descriptively named and typed `Indices.PutComposableTemplate` action. + +#### Nodes.HotThreads Action +- The `ThreadType` parameter has been renamed to just `Type` to match the query parameter it represents. Its corresponding `ThreadType` enum has been renamed to `NodesSampleType`. + +#### Nodes.Stats Action +- The `Groups` parameter's type has been corrected from `bool` to `string[]` to match the API which expects a comma-separated list of groups. + +#### Snapshot.CleanupRepository Action +- The `PostData body` parameter has been removed as the API does not expect a body to be sent. + +#### Tasks.List Action +- The `GroupBy` parameter's `GroupBy` enum has been renamed to `TasksGroupBy`. + +### OpenSearch.Client + +#### General +- The `MasterTimeout` parameters on all actions have been marked `[Obsolete]`, please migrate to using `ClusterManagerTimeout` if your OpenSearch cluster is at least version `2.0.0` as `MasterTimeout` may be removed in future major versions. +- The `ExpandWildcards` enum is now attributed with `[Flags]` to allow combining of multiple values e.g. `ExpandWildcards.Open | ExpandWildcards.Closed` to match open and closed indexes but not hidden. + +#### Cat.Indices Action +- The `Health` parameter now accepts a new `HealthStatus` enum instead of the `Health` enum. The values are identical and are now unified with other parts of the API that utilize the same enum. + +#### Cat.Master Action +- The `Cat.Master` action has been marked `[Obsolete]`, please migrate to using `Cat.ClusterManager` if your OpenSearch cluster is at least version 2.0.0 as `Cat.Master` may be removed in future major versions. + +#### Cat.Plugins Action +- The `IncludeBootstrap` parameter of the `Cat.Plugins` action has been removed as it was never supported by OpenSearch. + +#### Cluster.GetComponentTemplate Action +- The variant of this action accepting a template name has been corrected to only accept a single value rather than multiple as it was previously erroneously documented as accepting a comma-separated list. Attempting to use multiple names results in a server error. + +#### Cluster.Health Action +- The `Level` parameter now accepts a new `ClusterHealthLevel` enum instead of the `Level` enum. The values are the same except for the addition of the `AwarenessAttributes` value. +- The `WaitForStatus` parameter now accepts a new `HealthStatus` enum instead of the `WaitForStatus` enum. The values are identical and are now unified with other parts of the API that utilize the same enum. +- The `Status`, `Indices[].Status`, and `Indices[].Shards[].Status` properties in the response object now return the `HealthStatus` enum instead of the `Health` enum. The values are identical and are now unified with other parts of the API that utilize the same enum. + +#### Cluster.PostVotingConfigExclusions Action +- The `NodeIds` & `NodeNames` parameters now accept an array of strings instead of a single string to better represent the underlying API that accepts comma-separated lists. + +#### Cluster.Stats Action +- The `Nodes.OperatingSystem.PrettyNames` property in the response object's item type has been renamed from `ClusterOperatingSystemPrettyNane` to `ClusterOperatingSystemPrettyName` to correct a spelling mistake. + +#### Indices.GetComposableTemplate Action +- The variant of this action accepting a template name has been corrected to only accept a single value rather than multiple as it was previously erroneously documented as accepting a comma-separated list. Attempting to use multiple names results in a server error. + +#### Nodes.HotThreads Action +- The `ThreadType` parameter has been renamed to just `Type` to match the query parameter it represents. Its corresponding `ThreadType` enum has been renamed to `NodesSampleType`. + +#### Nodes.Stats Action +- The `Groups` parameter's type has been corrected from `bool` to `string[]` to match the cluster which expects a comma-separated list of groups. + +#### Tasks.List Action +- The `GroupBy` parameter's `GroupBy` enum has been renamed to `TasksGroupBy`. The enum otherwise remains unchanged. diff --git a/global.json b/global.json index d60815c6a2..650ed0fd4c 100644 --- a/global.json +++ b/global.json @@ -7,4 +7,4 @@ "version": "2.0.0", "doc_current": "2.0", "doc_branch": "2.x" -} +} \ No newline at end of file