Skip to content

Commit

Permalink
Clarify current stability guarantees
Browse files Browse the repository at this point in the history
This PR captures the current understanding of stability guarnatees.
I want to make sure it is explicitly visible until we make a decision
on open-telemetry#400

The most likely outcome of open-telemetry#400
is going to be stronger than current definition of "Stable.
  • Loading branch information
tigrannajaryan committed Jun 21, 2022
1 parent 9e7c1b3 commit dd74cc5
Showing 1 changed file with 26 additions and 6 deletions.
32 changes: 26 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,13 +39,33 @@ 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.
- Service operation names, parameter and return types 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.

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

0 comments on commit dd74cc5

Please sign in to comment.