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 experimental additions to Stable components #597

Merged
Changes from 1 commit
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
49 changes: 41 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,14 +83,47 @@ 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,
we recommend using a "development" sub-directory instead of adding them to any
protocol version. These protocols should not be used, except for
development/testing purposes.
### New Experimental Components

Sometimes we need to experiment with new components, for example to add a
completely new signal to OpenTelemetry. In this case, to define new experimental
components we recommend placing new proto files in a "development" sub-directory.
Such ioslated experimental components are excluded from
tigrannajaryan marked this conversation as resolved.
Show resolved Hide resolved
above [stability requirements](#stability-definition).

We recommend using
`Development`, `Alpha`, `Beta`, `Release Candidate`
[levels](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/0232-maturity-of-otel.md#maturity-levels)
to communicate different grades of readiness of new components.

Experimental components may be removed completely at the end of the experiment,
provided that they are not referenced from any `Stable` component.

Experiments which succeed, require a review to be marked `Stable`. Once marked
`Stable` they become subject to the [stability requirements](#stability-definition).

Another review must be conducted for in-development protocols to join the main project.
### Experimental Additions to Stable Components

New experimental fields or messages may be added in `Development` state to `Stable`
components. The experimental fields and messages withing `Stable components` are subject
tigrannajaryan marked this conversation as resolved.
Show resolved Hide resolved
to the full [stability requirements](#stability-definition), and in addition, they must be
clearly labeled as `Development` (or as any other non-`Stable` level) in the .proto file
source code.

If an experiment concludes and the previously added field or message is not needed
anymore, the field/message must stay, but it may be declared "deprecated". During all
phases of experimentation it must be clearly specified that the field or message may be
deprecated. Typically, deprecated fields are left empty by the senders and the recipients
that participate in experiments must expect during all experimental phases (including
_after_ the experiment is concluded) that the experimental field or message has an
empty value.

Experiments which succeed, require a review before the field or the message is marked
`Stable`.

## Generated Code

No guarantees are provided whatsoever about the stability of the code that
is generated from the .proto files by any particular code generator.
Loading