Skip to content

Commit

Permalink
Add UPGRADING.md to document breaking changes (#618)
Browse files Browse the repository at this point in the history
* Add UPGRADING.md to document breaking changes

Signed-off-by: Thomas Farr <tsfarr@amazon.com>

* Add link in README and add TOC

Signed-off-by: Thomas Farr <tsfarr@amazon.com>

---------

Signed-off-by: Thomas Farr <tsfarr@amazon.com>
  • Loading branch information
Xtansia authored Apr 24, 2024
1 parent 9d66221 commit 896fa4d
Show file tree
Hide file tree
Showing 6 changed files with 155 additions and 4 deletions.
4 changes: 3 additions & 1 deletion .github/bump-version.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
7 changes: 5 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
1 change: 1 addition & 0 deletions OpenSearch.sln
Original file line number Diff line number Diff line change
Expand Up @@ -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}"
Expand Down
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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/)
Expand Down
139 changes: 139 additions & 0 deletions UPGRADING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
<!-- TOC -->
* [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)
<!-- TOC -->

# 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[<index>].Status`, and `Indices[<index>].Shards[<shard>].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.
2 changes: 1 addition & 1 deletion global.json
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,4 @@
"version": "2.0.0",
"doc_current": "2.0",
"doc_branch": "2.x"
}
}

0 comments on commit 896fa4d

Please sign in to comment.