Skip to content

Commit 2080d87

Browse files
Clarify experimental additions to Stable components (#597)
The Entities SIG is planning a backward-compatible addition to the Resource, see the prototype here: tigrannajaryan#2 The change is compliant with existing stability requirements in this repository. However, our stability definition does not specify how such experimental additions to stable signals are expected to be done and what happens during and after the experiment. This PR adds more clarity in the process and further refines the stability definition to reinforce our strong commitment ot OTLP's stability.
1 parent 9098604 commit 2080d87

File tree

1 file changed

+41
-8
lines changed

1 file changed

+41
-8
lines changed

README.md

Lines changed: 41 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -83,14 +83,47 @@ All the additive changes above must be accompanied by an explanation about how
8383
new and old senders and receivers that implement the version of the protocol
8484
before and after the change interoperate.
8585

86-
No guarantees are provided whatsoever about the stability of the code that
87-
is generated from the .proto files by any particular code generator.
88-
8986
## Experiments
9087

91-
In some cases we are trying to experiment with different features. In this case,
92-
we recommend using a "development" sub-directory instead of adding them to any
93-
protocol version. These protocols should not be used, except for
94-
development/testing purposes.
88+
### New Experimental Components
89+
90+
Sometimes we need to experiment with new components, for example to add a
91+
completely new signal to OpenTelemetry. In this case, to define new experimental
92+
components we recommend placing new proto files in a "development" sub-directory.
93+
Such isolated experimental components are excluded from
94+
above [stability requirements](#stability-definition).
95+
96+
We recommend using
97+
`Development`, `Alpha`, `Beta`, `Release Candidate`
98+
[levels](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/0232-maturity-of-otel.md#maturity-levels)
99+
to communicate different grades of readiness of new components.
100+
101+
Experimental components may be removed completely at the end of the experiment,
102+
provided that they are not referenced from any `Stable` component.
103+
104+
Experiments which succeed, require a review to be marked `Stable`. Once marked
105+
`Stable` they become subject to the [stability requirements](#stability-definition).
95106

96-
Another review must be conducted for in-development protocols to join the main project.
107+
### Experimental Additions to Stable Components
108+
109+
New experimental fields or messages may be added in `Development` state to `Stable`
110+
components. The experimental fields and messages within `Stable components` are subject
111+
to the full [stability requirements](#stability-definition), and in addition, they must be
112+
clearly labeled as `Development` (or as any other non-`Stable` level) in the .proto file
113+
source code.
114+
115+
If an experiment concludes and the previously added field or message is not needed
116+
anymore, the field/message must stay, but it may be declared "deprecated". During all
117+
phases of experimentation it must be clearly specified that the field or message may be
118+
deprecated. Typically, deprecated fields are left empty by the senders and the recipients
119+
that participate in experiments must expect during all experimental phases (including
120+
_after_ the experiment is concluded) that the experimental field or message has an
121+
empty value.
122+
123+
Experiments which succeed, require a review before the field or the message is marked
124+
`Stable`.
125+
126+
## Generated Code
127+
128+
No guarantees are provided whatsoever about the stability of the code that
129+
is generated from the .proto files by any particular code generator.

0 commit comments

Comments
 (0)