From f5123107185346418427d301d1ea446ff4fbbba7 Mon Sep 17 00:00:00 2001 From: Ivy Gooch Date: Thu, 25 Apr 2024 16:18:45 +0000 Subject: [PATCH] Minor revisions per reviewer comments --- .../en/docs/Guides/Client SDKs/sdk-server.md | 28 +++++++------------ 1 file changed, 10 insertions(+), 18 deletions(-) diff --git a/site/content/en/docs/Guides/Client SDKs/sdk-server.md b/site/content/en/docs/Guides/Client SDKs/sdk-server.md index 37dcdd22b3..30f60959e6 100644 --- a/site/content/en/docs/Guides/Client SDKs/sdk-server.md +++ b/site/content/en/docs/Guides/Client SDKs/sdk-server.md @@ -11,30 +11,25 @@ description: "The SDK Server is a sidecar for a GameServer that will update the - The REST API is generated directly from the SDK .proto files. - All other SDK Client APIs are wrappers on top of the SDK proto definitions. -{{% feature publishVersion="1.43.0" %}} - -{{< alert title="Note" color="info">}} -This section is specifically about the SDK proto compatibility between Agones versions and deprecation policies. -{{< /alert >}} - +{{% feature publishVersion="1.40.0" %}} ## SDK Proto Compatibility Guarantees -In order to allow compatibility between game server binaries and sdk-server, a game server binary using Beta and Stable SDK protos must remain compatible with a newer sdk-server. -- Our SDK Server compatibility contract: If your game server uses a non-deprecated Stable API, your binary will be compatible for 10 releases (~1y) starting from the SDK version packaged +Our SDK Server compatibility contract: A game server binary using Beta and Stable SDKs will remain +compatible with a _newer_ `sdk-server`, within possible deprecation windows: +- If your game server uses a non-deprecated Stable API, your binary will be compatible for 10 releases (~1y) starting from the SDK version packaged. - For example, if the game server uses non-deprecated stable APIs in the 1.40 SDK, it will be compatible through the 1.50 SDK. - Stable APIs will almost certainly be compatible beyond 10 releases, but 10 releases is guaranteed. -- Similar to the compatibility contract for the Stable API, using a non-deprecated Beta API, your binary will be compatible for 5 releases (~6mo). -- Alpha SDK Protos (and APIs/RPCs) are subject to change between releases. +- If your game server uses a non-deprecated Beta API, your binary will be compatible for 5 releases (~6mo). +- Alpha SDK Protos are subject to change between releases. - A game server binary using Alpha SDKs may not be compatible with a newer sdk-server. - In Alpha, incompatible changes retaining the same SDK proto message name are allowed. - When we make incompatible Alpha changes, we will document the APIs involved. ## SDK Deprecation Policies -Breaking changes will be called out in upgrade documentation, alongside the build horizon, allowing operators to plan their upgrades. +Breaking changes will be called out in upgrade documentation to allow admins to plan their upgrades. ### Stable Deprecation Policies A Stable API may be marked as deprecated in release X and removed from Stable in release X+10. -Changes to the stable API must first flow through at least Beta. ### Beta Deprecation Policies -When a feature graduates from Beta to Stable at release X the API is in both protos from release X to release X+5. The Beta API is marked as deprecated in release X and removed from Beta in release X+5. +When a feature graduates from Beta to Stable at release X the API is in SDK proto surfaces from release X to release X+5. The Beta API is marked as deprecated in release X and removed from Beta in release X+5. A Beta API may be marked as deprecated in release X and removed from Beta in release X+5 without the API graduating to Stable. ### Alpha Deprecation Policies There is no guaranteed proto compatibility between releases for Alpha SDK protos. When an Alpha API graduates to Beta the API will be deleted from the Alpha proto with no overlapping release. @@ -42,11 +37,8 @@ An API may be removed from the Alpha proto during any release without graduating ## SDK Server APIs and Stability Levels -"Legacy" indicates that this API has been in the SDK Server in a release before we began tracking proto compatibility. - -{{< alert title="Note" color="info">}} -The Actions may differ from the Client SDKs depending on how each Client SDK is implemented. -{{< /alert >}} +"Legacy" indicates that this API has been in the SDK Server in a release before we began tracking proto compatibility. \ +The Actions may differ from the [Client SDKs]({{< relref "_index.md" >}}) depending on how each Client SDK is implemented. | Area | Action | Stable | Beta | Alpha | |---------------------|-----------------------|--------|------|--------|