docs: changelog and migration notes for v5 promotion

Track 6 of opensearch-project#835

Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>

Author: sean-

CHANGELOG.md

@@ -7,9 +7,9 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ### Added
 
 - Add `cmd/osgen` code generator for typed path builders and API consumer files from the OpenAPI spec
-- v5preview/opensearchapi: `NewClient` and `NewDefaultClient` now inject `opensearchtransport.NewDefaultRouter` when `config.Client.Router` is nil, opting every v5preview client into intelligent request routing by default. The `OPENSEARCH_GO_ROUTER` env var preserves its v4 semantics end-to-end: `=true`/`=1` enables auto-discovery (via `DiscoverNodesOnStart`); `=false`/`=0` suppresses both Router injection and auto-discovery; unset injects the Router without auto-discovery. v4's `opensearchapi.NewClient` is unchanged. ([#816](https://github.com/opensearch-project/opensearch-go/issues/816))
-- Add `envvars.Falsy(name)` helper that distinguishes "explicitly opted out" from "unset" (Truthy collapses both into false). Used by v5preview's router injection rule.
-- Add `v5preview/opensearchapi/` package: regenerated v5-track API surface produced by `cmd/osgen` from the OpenAPI spec. Fully typed Req/Resp/Params structs, sub-clients matching OpenSearch namespaces (`client.Cat`, `client.Cluster`, `client.Indices`, etc.), and a `plugins/` subtree for ML/k-NN/security/ISM/etc. Coexists with `opensearchapi/` during the v4 -> v5 transition; see `v5preview/opensearchapi/README.md` for usage and `UPGRADING.md` for migration guidance ([#650](https://github.com/opensearch-project/opensearch-go/issues/650))
+- `opensearchapi`: `NewClient` and `NewDefaultClient` inject `opensearchtransport.NewDefaultRouter` when `config.Client.Router` is nil, opting every client into intelligent request routing by default. The `OPENSEARCH_GO_ROUTER` env var controls the behavior: `=false`/`=0` suppresses both Router injection and auto-discovery; unset or any other value injects the Router and enables on-start discovery. ([#816](https://github.com/opensearch-project/opensearch-go/issues/816))
+- Add `envvars.Falsy(name)` helper that distinguishes "explicitly opted out" from "unset" (Truthy collapses both into false). Used by the router injection rule.
+- Add the code-generated `opensearchapi/` package: API surface produced by `cmd/osgen` from the OpenAPI spec. Fully typed Req/Resp/Params structs, sub-clients matching OpenSearch namespaces (`client.Cat`, `client.Cluster`, `client.Indices`, etc.), and a `plugins/` subtree for ML/k-NN/security/ISM/etc. Replaces the hand-written v4 package (previewed in the v4 line at `v5preview/opensearchapi/`); see `opensearchapi/README.md` for usage and `UPGRADING.md` for migration guidance ([#650](https://github.com/opensearch-project/opensearch-go/issues/650))
 - Add `primary_terms_map` and `split_shards_metadata` fields to ClusterState index metadata for OpenSearch >=3.6.0 compatibility
 - Add address resolver handler to rewrite discovered node addresses before they enter the connection pool ([#822](https://github.com/opensearch-project/opensearch-go/pull/822))
 - Add `InsecureSkipVerify` config option to disable TLS certificate verification without constructing a custom `http.Transport`, preserving `DefaultTransport` connection pooling, HTTP/2, and timeout defaults ([#786](https://github.com/opensearch-project/opensearch-go/issues/786))
@@ -102,7 +102,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
   - `Config.Errors *errmask.ErrorMask` replaces a single boolean: each bit suppresses one wrapper category. v4 defaults to `errmask.All` (mask everything, preserves pre-bitfield behavior); v5+ defaults to `errmask.Empty` (report everything)
   - `OPENSEARCH_GO_ERROR_MASK` environment variable overrides `Config.Errors` at runtime via comma-separated `+`/`-` tokens (lowercase snake_case wrapper names; unknown tokens silently dropped, debug-logged)
   - Both `(resp, error)` are non-nil on partial failure -- response is fully populated
-  - `v5preview/opensearchapi` ports the same model with spec-driven types (regenerated from the OpenAPI `x-error-responses` extension on every `cmd/osgen` run)
+  - The generated `opensearchapi` uses spec-driven types for the same model (regenerated from the OpenAPI `x-error-responses` extension on every `cmd/osgen` run)
 - Add `OperationClassifier` for zero-allocation HTTP method+path to `OperationID` mapping ([#816](https://github.com/opensearch-project/opensearch-go/issues/816))
   - Bit-packed `OperationID` (int64) encoding R/W flag, category, and minor operation
   - Masking helpers: `IsWrite`, `IsRead`, `Category`, `Minor`
@@ -159,7 +159,11 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Changed
 
-- **BREAKING**: `opensearchtransport.ConnectionObserver` interface gained an `OnAddressRewrite(AddressRewriteEvent)` method for the new address resolver feature (embedders of `BaseConnectionObserver` are unaffected) ([#822](https://github.com/opensearch-project/opensearch-go/pull/822))
+- **BREAKING**: Module path is now `github.com/opensearch-project/opensearch-go/v5`. Update import paths from `/v4` to `/v5`; the in-source `opensearchapi.X` package qualifier is unchanged
+- **BREAKING**: The code-generated API package is now the canonical `opensearchapi/`, replacing the hand-written v4 package (formerly previewed at `v5preview/opensearchapi/`). Req/Resp/Params types are fully typed and generated from the OpenAPI spec. See [`opensearchapi/MIGRATING.md`](opensearchapi/MIGRATING.md) for the field-level delta (`Indices` -> `Index`, `DocumentID` -> `ID`, optional `Params` becoming `*Params`, shared parameters moving into embedded `TimeoutParams`/`DebugParams`, `BulkResp.Items` becoming `[]BulkItem`) ([#650](https://github.com/opensearch-project/opensearch-go/issues/650))
+- **BREAKING**: The default Router is now on by default. `opensearchapi.NewClient`/`NewDefaultClient`, `opensearch.NewClient`, and `opensearchtransport.New` inject `opensearchtransport.NewDefaultRouter` (and enable on-start discovery) unless `OPENSEARCH_GO_ROUTER=false`. In v4 the router was opt-in via `OPENSEARCH_GO_ROUTER=true` ([#816](https://github.com/opensearch-project/opensearch-go/issues/816))
+- **BREAKING**: Partial-failure errors are now reported by default. `Config.Errors == nil` resolves to `errmask.Empty` (report every partial-failure category) instead of v4's `errmask.All` (mask everything). Set `Errors: errmask.New(errmask.All)` or `OPENSEARCH_GO_ERROR_MASK` to restore v4-style masking ([#816](https://github.com/opensearch-project/opensearch-go/issues/816))
+- **BREAKING**: `cmd/osgen` now treats the OpenSearch plugin acronyms `ISM`, `KNN`, `LTR`, `ML`, `PPL`, `SM`, `UBI`, and `WLM` as initialisms, so generated identifiers are all-uppercase per Go convention (matching the existing `API`, `HTTP`, `JSON`, etc. handling). Renames every affected `*_gen.go` type, path builder, and method, e.g. `IsmPolicy` -> `ISMPolicy`, `KnnStats` -> `KNNStats`, `SmPolicy` -> `SMPolicy`. Update any direct references to the renamed identifiers; the lowercase plugin package names (`ism`, `knn`, ...) are unchanged ([#863](https://github.com/opensearch-project/opensearch-go/issues/863))
 - **BREAKING**: `opensearch.Request` interface signature changed from `GetRequest() (*http.Request, error)` to `GetRequest(method string) (*http.Request, error)`. The HTTP method is now caller-provided rather than hardcoded per operation, enabling correct method selection for operations that support multiple HTTP methods (e.g. search supports both GET and POST). This only affects code that implements or calls `GetRequest` directly; standard usage through client methods (e.g. `client.Search(ctx, req)`) is unaffected ([#650](https://github.com/opensearch-project/opensearch-go/issues/650))
 - Bump CI and developer guide OpenSearch versions: compatibility matrix to 2.19.5, default integration test version to 3.6.0 ([#810](https://github.com/opensearch-project/opensearch-go/pull/810))
 - Include `_nodes.failures` detail in discovery error messages for diagnosing intermittent CI failures on older OpenSearch versions ([#823](https://github.com/opensearch-project/opensearch-go/pull/823))
@@ -212,9 +216,9 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Fix `opensearchtransport.Client.setReqGlobalHeader` comparing the per-request header value against the global header name, so a request-level header never suppressed the matching global default and both were sent ([#859](https://github.com/opensearch-project/opensearch-go/pull/859))
 - Fix gzip buffer-pool nil poisoning on compress error: `gzipCompressor.compress` returned `(nil, err)` while the caller's deferred `collectBuffer` still ran, putting a typed-nil `*bytes.Buffer` into the `sync.Pool` that panics on the next `Get().Reset()` ([#859](https://github.com/opensearch-project/opensearch-go/pull/859))
 - Fix `opensearchtransport.Client.Perform` silently dropping `io.ReadAll` errors during response buffering via `:=` shadowing; the read error now propagates wrapped in the new `opensearchtransport.ErrResponseBodyRead` sentinel, and `opensearch.Client.Do` classifies the `(resp != nil, err != nil)` case via `errors.Is` so only genuine body-read failures are labeled `ErrReadBody` (an unrelated transport error returned alongside a response, such as context cancellation during retry backoff, is no longer misreported as a read failure) ([#859](https://github.com/opensearch-project/opensearch-go/pull/859))
-- Fix error-response body not being closed in `opensearch.ParseError` and the v5preview `do()` no-decode path. The v5preview no-decode path now reads the body to EOF and re-wraps it in a `NopCloser` rather than discarding it, keeping the returned `resp.Body` readable and consistent with the `ParseError` path ([#859](https://github.com/opensearch-project/opensearch-go/pull/859))
+- Fix error-response body not being closed in `opensearch.ParseError` and the generated `opensearchapi` `do()` no-decode path. The no-decode path now reads the body to EOF and re-wraps it in a `NopCloser` rather than discarding it, keeping the returned `resp.Body` readable and consistent with the `ParseError` path ([#859](https://github.com/opensearch-project/opensearch-go/pull/859))
 - Fix response-body lifecycle on the raw `RoundTrip` paths that lack `Perform`'s buffering safety net, where closing a partially-read body defeated HTTP keep-alive: the stats poller (`cluster_health.go`) and discovery's `/_cat/shards`, `/_cluster/state/metadata`, and `/_nodes` paths now drain to EOF before close via a shared `drainAndClose` helper (covering both non-200 returns and `json.Decode` success paths that stop before EOF). `opensearch.Response.String()` is now non-consuming -- it restores `Body` with an in-memory reader after rendering, so logging a response no longer empties a body other code expects to read. The AWS v1 and v2 signers now close the request body on the read-error path in `hexEncodedSha256OfRequest` ([#859](https://github.com/opensearch-project/opensearch-go/pull/859))
-- Add typed response-format defaults for `v5preview/opensearchapi/` cat, list, ppl, and sql operations: when the caller leaves `Format` unset, the SDK now emits the value the typed Resp struct expects (`json` for cat/list/explain, `jdbc` for ppl/sql query) instead of letting the server fall back to a default the JSON decoder cannot handle.
+- Add typed response-format defaults for generated `opensearchapi/` cat, list, ppl, and sql operations: when the caller leaves `Format` unset, the SDK now emits the value the typed Resp struct expects (`json` for cat/list/explain, `jdbc` for ppl/sql query) instead of letting the server fall back to a default the JSON decoder cannot handle.
 - Replace `WaitForAllNodesReady` inline `require.Eventually` loop with a layered readiness FSM (`internal/test/readiness`) that observes per-node progression through `LayerTCP -> LayerHTTP -> LayerClusterJoin -> LayerStatsReady`, records transitions including regressions, and emits a structured per-node diagnostic with the full last cat-nodes response on timeout. Per-layer budgets are tuned for CI pessimism (cold JVM startup is the long pole); total budget for `TargetClusterReady` is 6.5 minutes. ([#650](https://github.com/opensearch-project/opensearch-go/issues/650))
 - Fix bulk indexer HTML-escaping `_id` and `routing` values containing `<`, `>`, or `&` characters, causing OpenSearch to store escaped values (e.g., `\u003croot_account\u003e` stored instead of `<root_account>`), leading to duplicate documents, unreachable data on read-by-ID paths, and potential shard routing mismatches. Present since the `json.Marshal` migration in 2021 (commit `3da59092`). Replace `json.Marshal` with `json.NewEncoder` + `SetEscapeHTML(false)` in `opensearchutil.worker.writeMeta` and `opensearchutil.JSONReader`; replace per-worker `aux []byte` with `sync.Pool`-backed `*bytes.Buffer`; add table-driven test coverage for `writeMeta` edge cases and refactor remaining `TestBulkIndexer` subtests to table-driven `require`-based style ([#824](https://github.com/opensearch-project/opensearch-go/pull/824))
 - Fix pool replacement orphaning resurrection goroutines during node discovery, causing connections to become permanently dead with no active health checker ([#786](https://github.com/opensearch-project/opensearch-go/pull/786))

DEVELOPER_GUIDE.md

@@ -385,9 +385,9 @@ make gh.checks.failed     # Only failed checks
 
 ## Code Generation
 
-The `cmd/osgen` tool generates typed path builder structs (`internal/path/`) and API consumer files (`v5preview/opensearchapi/`, `v5preview/opensearchapi/plugins/`) from the published [OpenSearch API specification](https://github.com/opensearch-project/opensearch-api-specification). It reads `x-operation-group`, `x-version-added`, `x-version-deprecated`, `x-version-removed`, and `x-error-responses` extensions from the spec to produce version-aware Go source.
+The `cmd/osgen` tool generates typed path builder structs (`internal/path/`) and API consumer files (`opensearchapi/`, `opensearchapi/plugins/`) from the published [OpenSearch API specification](https://github.com/opensearch-project/opensearch-api-specification). It reads `x-operation-group`, `x-version-added`, `x-version-deprecated`, `x-version-removed`, and `x-error-responses` extensions from the spec to produce version-aware Go source.
 
-The `v5preview/opensearchapi/` package is the v5-track API surface and coexists with the hand-written `opensearchapi/` package during the v4 -> v5 transition. New code should target `v5preview/opensearchapi/`; see `v5preview/opensearchapi/README.md` for usage and `UPGRADING.md` for migration guidance.
+The `opensearchapi/` package is the code-generated v5 API surface, produced by `cmd/osgen` from the spec. See `opensearchapi/README.md` for usage and `UPGRADING.md` for migration guidance.
 
 > **PRs that edit `*_gen.go` will be rejected.** These files are generated. To change them, send a PR against `cmd/osgen` (the generator) or against the [OpenSearch API specification](https://github.com/opensearch-project/opensearch-api-specification) (the input).
 
@@ -404,7 +404,7 @@ The `x-error-responses` extension on a spec operation declares the categories of
 
 Operations that declare two or more categories also get a per-op error container (e.g. `*MSearchErrors`) implementing `Unwrap() []error`, used when more than one category fires on a single response.
 
-The user-facing partial-failure model and best-practices guidance live in [`v5preview/opensearchapi/README.md`](v5preview/opensearchapi/README.md#partial-failure-errors) and [`guides/error_handling.md`](guides/error_handling.md). They deliberately omit `x-error-responses` terminology because callers don't need to read the spec to use the resulting errors. The spec-driven mechanics are documented here and in [`cmd/osgen/README.md`](cmd/osgen/README.md).
+The user-facing partial-failure model and best-practices guidance live in [`opensearchapi/README.md`](opensearchapi/README.md#partial-failure-errors) and [`guides/error_handling.md`](guides/error_handling.md). They deliberately omit `x-error-responses` terminology because callers don't need to read the spec to use the resulting errors. The spec-driven mechanics are documented here and in [`cmd/osgen/README.md`](cmd/osgen/README.md).
 
 To regenerate (downloads the spec automatically if not cached):
 

README.md

@@ -1,4 +1,4 @@
-[![Go Reference](https://pkg.go.dev/badge/github.com/opensearch-project/opensearch-go.svg)](https://pkg.go.dev/github.com/opensearch-project/opensearch-go/v4) [![Build](https://github.com/opensearch-project/opensearch-go/actions/workflows/lint.yml/badge.svg)](https://github.com/opensearch-project/opensearch-go/actions/workflows/lint.yml) [![Unit](https://github.com/opensearch-project/opensearch-go/actions/workflows/test-unit.yml/badge.svg)](https://github.com/opensearch-project/opensearch-go/actions/workflows/test-unit.yml) [![Integration](https://github.com/opensearch-project/opensearch-go/actions/workflows/test-integration.yml/badge.svg)](https://github.com/opensearch-project/opensearch-go/actions/workflows/test-integration.yml) [![codecov](https://codecov.io/gh/opensearch-project/opensearch-go/branch/main/graph/badge.svg?token=MI9g3KYHVx)](https://codecov.io/gh/opensearch-project/opensearch-go) [![Chat](https://img.shields.io/badge/chat-on%20forums-blue)](https://discuss.opendistrocommunity.dev/c/clients/) ![PRs welcome!](https://img.shields.io/badge/PRs-welcome!-success)
+[![Go Reference](https://pkg.go.dev/badge/github.com/opensearch-project/opensearch-go.svg)](https://pkg.go.dev/github.com/opensearch-project/opensearch-go/v5) [![Build](https://github.com/opensearch-project/opensearch-go/actions/workflows/lint.yml/badge.svg)](https://github.com/opensearch-project/opensearch-go/actions/workflows/lint.yml) [![Unit](https://github.com/opensearch-project/opensearch-go/actions/workflows/test-unit.yml/badge.svg)](https://github.com/opensearch-project/opensearch-go/actions/workflows/test-unit.yml) [![Integration](https://github.com/opensearch-project/opensearch-go/actions/workflows/test-integration.yml/badge.svg)](https://github.com/opensearch-project/opensearch-go/actions/workflows/test-integration.yml) [![codecov](https://codecov.io/gh/opensearch-project/opensearch-go/branch/main/graph/badge.svg?token=MI9g3KYHVx)](https://codecov.io/gh/opensearch-project/opensearch-go) [![Chat](https://img.shields.io/badge/chat-on%20forums-blue)](https://discuss.opendistrocommunity.dev/c/clients/) ![PRs welcome!](https://img.shields.io/badge/PRs-welcome!-success)
 
 ![OpenSearch logo](OpenSearch.svg)
 
@@ -22,7 +22,7 @@ The client supports automatic node discovery, request-based connection routing,
 - [Developer Guide](DEVELOPER_GUIDE.md)
 - [User Guide](USER_GUIDE.md)
 - [Documentation](https://opensearch.org/docs/latest/clients/go/)
-- [API Documentation](https://pkg.go.dev/github.com/opensearch-project/opensearch-go/v4)
+- [API Documentation](https://pkg.go.dev/github.com/opensearch-project/opensearch-go/v5)
 - Need help? Try [Forums](https://discuss.opendistrocommunity.dev/c/clients/)
 - [Project Principles](https://opensearch.org/#principles)
 - [Contributing to OpenSearch](CONTRIBUTING.md)