mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-17 05:31:16 +08:00
57 lines
5.2 KiB
Plaintext
57 lines
5.2 KiB
Plaintext
---
|
|
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
title: "API Compatibility"
|
|
description: "Review OpenShell API versioning, deprecation, schema evolution, and client/server compatibility guarantees."
|
|
position: 6
|
|
---
|
|
The compatibility policy covers published gRPC services, Protobuf messages,
|
|
generated SDK interfaces, documented error behavior, and public Driver,
|
|
Interceptor, and Middleware APIs.
|
|
|
|
## Compatibility Promise
|
|
|
|
| Release phase | Compatibility policy |
|
|
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Beta | Patch releases are backward compatible. A minor release may contain a breaking API change only after the affected API is deprecated in a preceding minor release. The release includes migration guidance and coordinated SDK updates. |
|
|
| Stable | Minor and patch releases are backward compatible within an API major version. Breaking changes use a new versioned Protobuf package and API major version. The previous stable API remains supported for at least 12 months or two minor releases after its replacement, whichever is longer. |
|
|
|
|
## Change Policy
|
|
|
|
| Change | Policy |
|
|
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Additive | New optional fields, messages, methods, and enum values may be added when existing requests and responses retain their meaning and defaults. |
|
|
| Deprecating | The existing element remains functional while the schema and documentation identify it as deprecated, name its replacement, and state its planned removal release. |
|
|
| Breaking | Removing or renaming an API element, reusing or renumbering a field, changing a field type or cardinality, making an existing input required, or changing documented semantics follows the beta process or ships in a new stable API major version. |
|
|
|
|
## Client and Server Compatibility
|
|
|
|
OpenShell evaluates compatibility in both client/server directions. Clients
|
|
include the CLI, TUI, and supported SDKs.
|
|
|
|
| Combination | Expected behavior |
|
|
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Older client with newer server | Operations available to the client retain their request, response, error, and behavioral semantics throughout the support window. |
|
|
| Newer client with older server | Features shared by both releases continue to work. Features unavailable from the server are hidden or return an actionable unsupported-version error. |
|
|
| Different patch versions | Existing features remain compatible in both directions. |
|
|
| Different API major versions | Compatibility depends on the server continuing to expose the older API version during its deprecation window. |
|
|
|
|
Clients use the capabilities advertised by the server to select supported
|
|
behavior instead of inferring feature availability from the server version
|
|
alone.
|
|
|
|
Release validation exercises the oldest supported release of the CLI, TUI, and
|
|
each SDK against the candidate server. Current clients run the shared-feature
|
|
suite against each server release in the support window. Capability-specific
|
|
tests verify the behavior of features that are newer than the server.
|
|
|
|
## Schema Compatibility
|
|
|
|
Removed Protobuf field and enum numbers and names remain reserved and are never
|
|
reused. CI compares API changes with the default branch for source, wire, and
|
|
JSON compatibility. Client/server validation covers request semantics, response
|
|
semantics, documented errors, and feature negotiation.
|
|
|
|
For supported platforms, clients, compute drivers, Kubernetes distributions,
|
|
and SDK versions, refer to the [Support Matrix](/reference/support-matrix).
|