Skip to content
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

Merged
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 28 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

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?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say no.

- Field numbers will not change.
- Numbers assigned to enum choices will not change.
- Service names and service package names will not change.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does "service package name" mean?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The package name where the service is declared, e.g.:

package opentelemetry.proto.collector.trace.v1;

- 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
Copy link
Member

@reyang reyang Jun 28, 2022

Choose a reason for hiding this comment

The 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.
What about things that are not included in these lists? - are they allowed or disallowed?

E.g. it'll be great to have one of the following statements:

  • Anything that is not in the allowed list, are not allowed.
  • Anything that is not in the disallowed list, are allowed.
  • Anything that is not in the allowed list AND not in the disallowed list, is currently UNDEFINED and might be allowed/disallowed in the future.

Copy link
Member Author

Choose a reason for hiding this comment

The 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it possible to add more Enum values? Above it just says - Numbers assigned to enum choices will not change., which would still be fulfilled if adding more choices, right?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is possible, numbers already assigned cannot be reassigned or changed

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good, do we need to call it out in the list of allowed changes? This is also somewhat related to @reyang's comment, as it would be UNDEFINED if we don't add it.

- 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

Expand Down