SDK proto compatibility guarantees and deprecation policies documentation #3774

igooch · 2024-04-17T18:24:11Z

What type of PR is this?

/kind documentation

What this PR does / Why we need it:

As part of work on In-place Agones Upgrades #3766 we are going to explicitly guarantee certain proto versions during upgrade and this documents that contract.

Which issue(s) this PR fixes:

Working on #3767

Special notes for your reviewer:

agones-bot · 2024-04-17T18:37:08Z

Build Failed 😱

Build Id: 6cdcdd1b-9e58-4226-8a75-feccde6144f1

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

agones-bot · 2024-04-17T20:14:20Z

Build Succeeded 👏

Build Id: e052afdd-79b3-401c-b5c3-1925005d2485

The following development artifacts have been built, and will exist for the next 30 days:

A preview of the website (the last 30 builds are retained):

https://35bb0ca-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/3774/head:pr_3774 && git checkout pr_3774
helm install agones ./install/helm/agones --namespace agones-system --set agones.image.registry=us-docker.pkg.dev/agones-images/ci --set agones.image.tag=1.40.0-dev-35bb0ca-amd64

agones-bot · 2024-04-18T17:30:38Z

Build Succeeded 👏

Build Id: 4863b84b-6c79-4432-93b0-6afffc87c23f

The following development artifacts have been built, and will exist for the next 30 days:

A preview of the website (the last 30 builds are retained):

https://2397fe5-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/3774/head:pr_3774 && git checkout pr_3774
helm install agones ./install/helm/agones --namespace agones-system --set agones.image.registry=us-docker.pkg.dev/agones-images/ci --set agones.image.tag=1.40.0-dev-2397fe5-amd64

site/content/en/docs/Guides/Client SDKs/sdk-server.md

markmandel

Meta question -- I'm wondering if this (and all other details on in-place upgrades), should be in: https://agones.dev/site/docs/installation/upgrading/

Or that section shouid be fleshed out into separate sections, since ultimately the CUJ is "I want to update in place", not "I want to learn how the sdk-server works" ? (Please correct me if I'm wrong).

igooch · 2024-04-25T16:39:48Z

Meta question -- I'm wondering if this (and all other details on in-place upgrades), should be in: https://agones.dev/site/docs/installation/upgrading/

We definitely want to have the in-place upgrades info there. Probably most of what's in this PR could also go in there. If we switch it over I would probably both feature-gate it to when in-place upgrades is released in Alpha, and make even more explicit from what number release the info applies.

agones-bot · 2024-04-25T18:10:43Z

Build Succeeded 👏

Build Id: a99431d6-e184-4d18-861d-afe579815c29

The following development artifacts have been built, and will exist for the next 30 days:

A preview of the website (the last 30 builds are retained):

https://fa4833a-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/3774/head:pr_3774 && git checkout pr_3774
helm install agones ./install/helm/agones --namespace agones-system --set agones.image.registry=us-docker.pkg.dev/agones-images/ci --set agones.image.tag=1.41.0-dev-fa4833a-amd64

site/content/en/docs/Installation/upgrading.md

zmerlynn

In general, looks pretty good to me and agreed on putting it in Upgrades.

I'd like to resolve whether to gate this "later" or 1.41: #3774 (comment)

And @markmandel should give it a pass to see if it makes sense.

agones-bot · 2024-04-26T22:51:43Z

Build Failed 😱

Build Id: 56deae11-2729-4d89-9ab5-387fb2bd1c9f

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

agones-bot · 2024-04-29T19:36:07Z

Build Succeeded 👏

Build Id: 6efe511b-85d9-498a-b41d-e8d76594b1af

The following development artifacts have been built, and will exist for the next 30 days:

A preview of the website (the last 30 builds are retained):

https://af68e81-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/3774/head:pr_3774 && git checkout pr_3774
helm install agones ./install/helm/agones --namespace agones-system --set agones.image.registry=us-docker.pkg.dev/agones-images/ci --set agones.image.tag=1.41.0-dev-af68e81-amd64

zmerlynn

LGTM - would like @markmandel to give it a pass, though.

markmandel

Good start! I think if we focus on the why rather than the how at least to start, this will round out quite nicely.

site/content/en/docs/Guides/Client SDKs/sdk-server.md

markmandel · 2024-05-02T17:58:12Z

site/content/en/docs/Installation/upgrading.md

 1. Run any other tests to ensure the Agones installation is still working as expected.
 1. Close your maintenance window.
 7. Congratulations - you have now upgraded to a new version of Kubernetes! 👍
+
+{{% feature publishVersion="1.41.0" %}}
+## SDK Proto Compatibility Guarantees as of Agones v1.41.0


So I'm going to come back to CUJ on this one. This is docs on what we guarantee at a technical level, but not why we guarantee it, or why as an end user, should I care about this documentation? What is the end user trying to do here?

Is this the beginning of supporting in-place upgrades? If so, shall we give it that header and description, and then go into details of how? (I think this is where we should start)

Just on headers and structure, I would argue it's not a SDK Proto Compatibility that's what we have here, but actually SDK Compatibility. The implementation details (sidecar + proto) is actually not important to the end user - it's that the SDK itself has compatibility guarantees.

We should still cover some of the how (since people will likely want to know), but it's not the top level element of the documentation I don't think.

This reason for "proto" is specifically SDK proto / SDK Server and does not apply to the client. The SDK client could be well out of date. For instance the C++, Rust, Unity, and Unreal clients don't have CountsAndLists at all even though it's going into Beta, and if no one updates them they may not have those features in GA. So it should be clear to the reader that this guarantee does not apply to the SDK clients. (Also the reason for using "proto" instead of "API" which is a bit more ambiguous.) If we were guaranteeing SDK clients we would need to have a separate discussion about deprecating clients if no one updates them regularly.

But as an end user I don't care about the proto - I want to know if I am using my SDK client, will that stay backward compatible.

Much of this is covered in this section of the design doc: #3766 (comment) - which for this documentation is the more relevant part.

The SDK client could be well out of date.

Why would that mater?

or instance the C++, Rust, Unity, and Unreal clients don't have CountsAndLists at all even though it's going into Beta, and if no one updates them they may not have those features in GA.

Not an issue for backward or forward compatability.

If we were guaranteeing SDK clients we would need to have a separate discussion about deprecating clients if no one updates them regularly.

I'm not sure why we would do that? Assuming the proto doesn't change (which it shouldn't for stable APIs, they should just work forever -- but the linked above RFC covers this.

For instance if the client has an API in Beta and no one moves it to GA, the Beta will break after 5 releases, so anyone using that client can't move past the version when it's removed from Beta. Which means that we would have to track version compatibility horizons for each client. The Users are not required to update Client SDK in game server binaries except for SDK proto deprecations, or breaking Alpha API changes. assumes that all clients are up to date, which is an incorrect assumption. (A side note that this doesn't apply to the REST API which is automatically generated from the proto.) For all non-REST APIs, there may be no Client SDK to update to.

The assumption is that the proto may change. It's unlikely, but we reserve the right to add and remove fields and methods within our deprecation policies. So if a field or method is removed and the client is not updated, the client will be broken starting at a particular version. That's why, if we are guaranteeing the clients, we should have a discussion on deprecating clients, or at least marking them as "waiting for maintainer" or similar. I would argue that we shouldn't take on guaranteeing and maintaining all clients.

For instance if the client has an API in Beta and no one moves it to GA, the Beta will break after 5 releases, so anyone using that client can't move past the version when it's removed from Beta

I don't think it will. There implementation doesn't go away - it's still there, it will all still work.

Beta Client SDK APIs should be considered generally stable, but we may alter the parameters/returns if we need to

Beta APIs may change, but that's also the risk of using Beta APIs - but are definitely considered more stable than Alpha.

We foresee that updating Client SDKs in game server binaries will be yearly toil, if using Stable APIs, or semiannual toil, if using any Beta API; this toil can be as simple as verifying that there were no deprecations in the period involved. Given how stable our core APIs have been, it may be possible to go multiple years without updating the Client SDK.

I am seeing some more room here to flesh out exactly what is guaranteed with a Beta SDK though - I think there's some ambiguity here that could be more concrete for sure.

site/content/en/docs/Installation/upgrading.md

agones-bot · 2024-05-06T17:42:06Z

Build Succeeded 👏

Build Id: 46514077-3708-4c8c-b15d-e507e0ea4daf

The following development artifacts have been built, and will exist for the next 30 days:

A preview of the website (the last 30 builds are retained):

https://787587c-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/3774/head:pr_3774 && git checkout pr_3774
helm install agones ./install/helm/agones --namespace agones-system --set agones.image.registry=us-docker.pkg.dev/agones-images/ci --set agones.image.tag=1.41.0-dev-787587c-amd64

site/content/en/docs/Installation/upgrading.md

…he upgrades page

agones-bot · 2024-05-10T18:00:51Z

Build Succeeded 👏

Build Id: ce94f97e-57d7-4847-94e0-3413d8fc653a

The following development artifacts have been built, and will exist for the next 30 days:

A preview of the website (the last 30 builds are retained):

https://25a2709-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/3774/head:pr_3774 && git checkout pr_3774
helm install agones ./install/helm/agones --namespace agones-system --set agones.image.registry=us-docker.pkg.dev/agones-images/ci --set agones.image.tag=1.41.0-dev-25a2709-amd64

markmandel

Mainly nits, but I like this so much more!

We could probably add some details on the "how" at later stage, depending on if that's information people want or need.

Once nits are done, happy to merge.

site/content/en/docs/Installation/upgrading.md

markmandel

I think this is it (hopefully 😆). Words are hard.

site/content/en/docs/Installation/upgrading.md

agones-bot · 2024-05-11T00:17:09Z

Build Failed 😱

Build Id: 6d19b32c-6fb8-47f4-9090-18f46b472544

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

markmandel · 2024-05-11T01:41:04Z

Flaky 1.29 Autopilot. Cleared the cluster and trying again.

agones-bot · 2024-05-11T03:29:02Z

Build Succeeded 👏

Build Id: dd5563ed-ad3b-4e5d-ad1b-a4c03749b990

The following development artifacts have been built, and will exist for the next 30 days:

A preview of the website (the last 30 builds are retained):

https://a234f32-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/3774/head:pr_3774 && git checkout pr_3774
helm install agones ./install/helm/agones --namespace agones-system --set agones.image.registry=us-docker.pkg.dev/agones-images/ci --set agones.image.tag=1.41.0-dev-a234f32-amd64

zmerlynn · 2024-05-14T16:13:52Z

Looks great! Sent #3827 to fix a minor issue.

github-actions bot added the kind/documentation Documentation for Agones label Apr 17, 2024

igooch changed the title ~~SDK proto compatibility guarantees and deprecation policies documentaiton~~ SDK proto compatibility guarantees and deprecation policies documentation Apr 17, 2024

github-actions bot added the size/S label Apr 17, 2024

igooch force-pushed the in-place-upgrades branch 2 times, most recently from 809c899 to 35bb0ca Compare April 17, 2024 19:03

igooch force-pushed the in-place-upgrades branch from 35bb0ca to 2397fe5 Compare April 18, 2024 16:22

igooch marked this pull request as ready for review April 18, 2024 16:23

zmerlynn reviewed Apr 23, 2024

View reviewed changes

markmandel reviewed Apr 24, 2024

View reviewed changes

igooch force-pushed the in-place-upgrades branch 2 times, most recently from f5ebf8c to 83ea058 Compare April 25, 2024 16:29

zmerlynn reviewed Apr 25, 2024

View reviewed changes

site/content/en/docs/Installation/upgrading.md Outdated Show resolved Hide resolved

zmerlynn reviewed Apr 25, 2024

View reviewed changes

igooch force-pushed the in-place-upgrades branch 2 times, most recently from ea67a83 to 3ab9c89 Compare April 26, 2024 22:23

igooch force-pushed the in-place-upgrades branch from 3ab9c89 to af68e81 Compare April 29, 2024 18:29

zmerlynn reviewed Apr 30, 2024

View reviewed changes

markmandel reviewed May 2, 2024

View reviewed changes

site/content/en/docs/Installation/upgrading.md Outdated Show resolved Hide resolved

igooch force-pushed the in-place-upgrades branch 3 times, most recently from 153b0b7 to 787587c Compare May 6, 2024 16:41

markmandel reviewed May 6, 2024

View reviewed changes

site/content/en/docs/Installation/upgrading.md Outdated Show resolved Hide resolved

igooch added 4 commits May 10, 2024 16:14

SDK proto compatibility guarantees and deprecation policies.

f36d078

Minor revisions per reviewer comments

af1eb29

Moves SDK proto compatibity and deprecation policy documentation to t…

3b27c72

…he upgrades page

Small wording changes

2b044cc

igooch force-pushed the in-place-upgrades branch from 787587c to 2b044cc Compare May 10, 2024 16:14

Additional CUJ type questions to the upgrades path

25a2709

github-actions bot added the size/M label May 10, 2024

markmandel reviewed May 10, 2024

View reviewed changes

igooch force-pushed the in-place-upgrades branch 3 times, most recently from 6804e81 to a50158a Compare May 10, 2024 23:10

markmandel reviewed May 10, 2024

View reviewed changes

site/content/en/docs/Installation/upgrading.md Outdated Show resolved Hide resolved

site/content/en/docs/Installation/upgrading.md Outdated Show resolved Hide resolved

Changes per reviewer comments

a234f32

igooch force-pushed the in-place-upgrades branch from a50158a to a234f32 Compare May 10, 2024 23:26

markmandel approved these changes May 10, 2024

View reviewed changes

markmandel enabled auto-merge (squash) May 10, 2024 23:30

markmandel merged commit 1b06e94 into googleforgames:main May 11, 2024
4 checks passed

zmerlynn mentioned this pull request May 14, 2024

Fix dangling "as of" #3827

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

SDK proto compatibility guarantees and deprecation policies documentation #3774

SDK proto compatibility guarantees and deprecation policies documentation #3774

igooch commented Apr 17, 2024 •

edited

Loading

agones-bot commented Apr 17, 2024

agones-bot commented Apr 17, 2024

agones-bot commented Apr 18, 2024

markmandel left a comment

igooch commented Apr 25, 2024

agones-bot commented Apr 25, 2024

zmerlynn left a comment

agones-bot commented Apr 26, 2024

agones-bot commented Apr 29, 2024

zmerlynn left a comment

markmandel left a comment

markmandel May 2, 2024

igooch May 6, 2024

markmandel May 6, 2024

igooch May 7, 2024

markmandel May 8, 2024

agones-bot commented May 6, 2024

agones-bot commented May 10, 2024

markmandel left a comment

markmandel left a comment

agones-bot commented May 11, 2024

markmandel commented May 11, 2024

agones-bot commented May 11, 2024

zmerlynn commented May 14, 2024

SDK proto compatibility guarantees and deprecation policies documentation #3774

SDK proto compatibility guarantees and deprecation policies documentation #3774

Conversation

igooch commented Apr 17, 2024 • edited Loading

agones-bot commented Apr 17, 2024

agones-bot commented Apr 17, 2024

agones-bot commented Apr 18, 2024

markmandel left a comment

Choose a reason for hiding this comment

igooch commented Apr 25, 2024

agones-bot commented Apr 25, 2024

zmerlynn left a comment

Choose a reason for hiding this comment

agones-bot commented Apr 26, 2024

agones-bot commented Apr 29, 2024

zmerlynn left a comment

Choose a reason for hiding this comment

markmandel left a comment

Choose a reason for hiding this comment

markmandel May 2, 2024

Choose a reason for hiding this comment

igooch May 6, 2024

Choose a reason for hiding this comment

markmandel May 6, 2024

Choose a reason for hiding this comment

igooch May 7, 2024

Choose a reason for hiding this comment

markmandel May 8, 2024

Choose a reason for hiding this comment

agones-bot commented May 6, 2024

agones-bot commented May 10, 2024

markmandel left a comment

Choose a reason for hiding this comment

markmandel left a comment

Choose a reason for hiding this comment

agones-bot commented May 11, 2024

markmandel commented May 11, 2024

agones-bot commented May 11, 2024

zmerlynn commented May 14, 2024

igooch commented Apr 17, 2024 •

edited

Loading