Skip to content

Commit

Permalink
Minor revisions per reviewer comments
Browse files Browse the repository at this point in the history
  • Loading branch information
igooch committed May 6, 2024
1 parent d591747 commit f6128af
Showing 1 changed file with 10 additions and 18 deletions.
28 changes: 10 additions & 18 deletions site/content/en/docs/Guides/Client SDKs/sdk-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,42 +11,34 @@ 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.
An API may be removed from the Alpha proto during any release without graduating to Beta.

## 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 |
|---------------------|-----------------------|--------|------|--------|
Expand Down

0 comments on commit f6128af

Please sign in to comment.