From 217a212c3f56cdcb6167e8a62dd4881ed3f8249d Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Mon, 17 Oct 2022 21:01:16 -0400 Subject: [PATCH] Define OTLP 1.0 Stability guarantees Resolves https://github.com/open-telemetry/opentelemetry-proto/issues/400 --- README.md | 30 +++++++++++------------------- 1 file changed, 11 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 5a8a1710d..e552225a6 100644 --- a/README.md +++ b/README.md @@ -48,23 +48,18 @@ for definition of maturity levels). Components marked `Stable` provide the following guarantees: - Field types, numbers and names 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. - -The following changes are allowed: - -- Message names may change. -- Enum names may change. -- Enum choice names may change. This is allowed because enum choice names are not sent on - the wire. -- 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. - -Note that none of the above allowed changes affects the binary wire representation or the -JSON wire representation. +- Service method names will not change. +- Service method parameter names will not change. +- Service method parameter types and return types will not change. +- Service method kind (unary vs streaming) 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. +- `optional` and `repeated` declarators of existing fields will not change. +- No existing symbol will be deleted. The following additive changes are allowed: @@ -79,9 +74,6 @@ All the additive 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 -is generated from the .proto files by any particular code generator. - ## Experiments In some cases we are trying to experiment with different features. In this case,