Laremere commented 4 years ago

1.0 will imply some level of API and functional stability. The goal of this proposal is to define precisely what we are going to consider locked at 1.0, and what is subject to change. If we wanted to break these guarantees post 1.0, it would require going to 2.0.

Assignees at time of issue creation are required approvers. Please approve, or leave comments. Post approval, this will make its way into the documentation.

Covered

These areas are covered by a backwards compatibility guarantee. Upgrading to a new version will not require any changes to these parts of your system.

gRPC / Protobuf

Using gRPC to connect to Open Match with the proto files defined with the 1.0 release will continue to work. Open Match MAY choose to handle fields differently, provided it does not break any other compatibility guarantees. Open Match MAY make backwards compatible changes, such as adding a new value to an enum, or adding a new optional field. Uses of Open Match proto fields MUST be able to handle unknown enum values.

General Computation Model and Behavior

Implementations using Open Match are expected to continue functioning after an upgrade. Open Match SHOULD NOT make changes that require code logic changes, use of new or changes protobuf fields, nor rethinking of your matchmaking system architecture.

Not Covered

These items are explicitly not covered by any backwards compatibility. This means that upgrading to a new version may involve changes in these parts of your system. While Open Match updates SHOULD avoid undue amount of changes, what it doesn’t guarantee is defined to help avoid incorrect expectations.

Exact Computational Behavior

The exact behavior of Open Match is NOT guaranteed. Open Match may choose to fix what we reasonably consider a bug (or unintentionally introduce bugs) version to version. Take reasonable care to not rely on behavior such as timing or return order when it is not well defined in the API documentation. Always test a new version before going to production to detect any unexpected consequences of upgrading.

Deployment

All of the following are subject to change:

The steps to deploy Open Match in a Kubernetes cluster
The Kubernetes objects created
The minimum required Kubernetes version

The services provided by Open Match SHOULD NOT be removed or changed in a way which requires changes in how to connect other services to Open Match.

Best practices

The best way to build a matchmaker using Open Match is expected to evolve over time. Open Match SHOULD NOT perform significantly worse than previous versions on any tasks. There may be new ways to use Open Match to achieve better results which require code changes that you can choose to use or not.

Not Covered, but may be covered in the future

These items are current not covered by a backwards compatibility guarantee. However it is reasonable to consider including in a future backwards compatibility guarantee. Generally it’s here because the implementation has received little feedback.

Configuration

The method and format of configuration of Open Match is NOT guaranteed. It is currently a relatively small surface area that is not connected to larger areas of concern. Open Match MAY add a new required configuration field, or remove an old one. Open Match SHOULD NOT make changes to configuration without significant justification.

http/json

Open Match’s support of connecting with HTTP and using JSON objects (instead of gRPC and Protobuf) has received little feedback and testing.

Metrics

The list of open consensus metrics exported by Open Match and what data they report MAY change.

Features explicitly marked as alpha or beta.

Any protobuf fields, messages, or services which are marked as alpha or beta are subject to change. Breaking existing implementations which rely on such features will not be a consideration when discussing the merits of changes.

markmandel commented 4 years ago

LGTM! You may want to mention it, although you don't have to work out the details right now, but you may want to also have Alpha/Beta feature gating of new features. (This is how Agones does it: https://agones.dev/site/docs/guides/feature-stages/)

This means you aren't locked into backward compatibility as soon as you drop a feature, and have some room to experiment / get community feedback / etc.

sawagh commented 4 years ago

LGTM.

For the things in the Not Covered, but may be covered in the future section. I would start with everything listed there as Not Covered for v1.0 guarantee. Once we have agreement on that, I think the may be covered in the future disclaimer can be dropped in the final guarantees to avoid confusion.

If that is called out for the purpose of this issue to get opinions, thats great. As we resolve this issue and move these guarantees to the web page, just Covered / Not Covered sections would be clear.