-
Notifications
You must be signed in to change notification settings - Fork 265
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Clarify current stability guarantees #406
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||
---|---|---|---|---|
|
@@ -39,13 +39,35 @@ All messages | Alpha | | |||
(See [maturity-matrix.yaml](https://github.com/open-telemetry/community/blob/47813530864b9fe5a5146f466a58bd2bb94edc72/maturity-matrix.yaml#L57) | ||||
for definition of maturity levels). | ||||
|
||||
Note that maturity guarantees apply only to wire-level compatibility for the binary | ||||
Protobuf serialization. Neither message, field, nor enum names of Protobuf messages | ||||
are visible on the wire and are not considered part of the guarantees. We are free | ||||
to make a change to the names. | ||||
## Stability Definition | ||||
|
||||
In the future when OTLP/JSON is declared stable, field names will also become part of | ||||
the maturity guarantees, since field names are visible on the wire for JSON encoding. | ||||
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. | ||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What does "service package name" mean? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The
|
||||
- Service operation names, parameter and return types will not change. | ||||
|
||||
The following changes are allowed: | ||||
tigrannajaryan marked this conversation as resolved.
Show resolved
Hide resolved
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This change covers a list of things that are disallowed and a list of things that are allowed. E.g. it'll be great to have one of the following statements:
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think we should go with UNDEFINED. That's by default how I think about our specs. If it is not specified then it is undefined and can become defined later. |
||||
|
||||
- Message names may change. | ||||
- Field names may change. | ||||
- Enum names may change. | ||||
- Enum choice names may change. | ||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is it possible to add more Enum values? Above it just says There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It is possible, numbers already assigned cannot be reassigned or changed There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||||
- 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. | ||||
|
||||
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 | ||||
|
||||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is the "optional" attribute considered part of the type?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would say no.