diff --git a/README.md b/README.md index 9c5c637fd..5fcf5591d 100644 --- a/README.md +++ b/README.md @@ -43,32 +43,34 @@ for definition of maturity levels). Components marked `Stable` provide the following guarantees: -- Field types will not change. -- Field numbers will not change. -- Numbers assigned to enum choices will not change. -- Service names and service package names will not change. -- Service operation names, parameter and return types will not change. +- Field types, numbers and names will not change. +- Names of messages and enums will not change. +- Names of enum choices and numbers assigned to enum choices will not change. +- The location of messages and enums, i.e. whether they are declared at the top lexical + scope or nested inside another message will not change. +- Package names and directory structure will not change. +- gRPC service names, service method names, parameters and return types will not change. +- Service method parameter names will not change. +- Service method kind (unary vs streaming) will not change. +- No existing symbol will be deleted. +- `optional` and `repeated` declarators of existing fields will not change. The following changes are allowed: -- Message names may change. -- Field names may change. -- Enum names may change. -- Enum choice names may change. -- The location of messages and enums, i.e. whether they are declared at the top - lexical scope or nested inside another message may change. -- Package names may change. -- Directory structure, location and the name of the files may change. +- Adding new fields to existing messages. +- Adding new messages or enums. +- Adding new choices to existing enums. +- Adding new choices to existing oneof fields. +- Adding new services. +- Adding new methods to existing services. -Note that none of the above allowed changes affects the binary wire representation. +All the allowed changes above must be accompanied by an explanation about how +new and old senders and receivers that implement the version of the protocol +before and after the change interoperate. -No guarantees are provided whatsoever about the stability of the code that +WARNING: No guarantees are provided whatsoever about the stability of the code that is generated from the .proto files by any particular code generator. -In the future when OTLP/JSON is declared stable, several of the changes that -are currently allowed will become disallowed since they are visible on the wire -for JSON encoding. - ## Experiments In some cases we are trying to experiment with different features. In this case,