Add a variety of key definitions surrounding stability #142
Conversation
|
This was discussed at 03-Feb-2025 WG call, this needs to be reviewed by the next call (17-Feb) |
README.md
Outdated
|
|
||
| The primary objective of stability is to protect users from breaking changes. That is, users providing configuration conforming to a particular stable version of the schema should be able to reliably upgrade minor and patch versions without risk that their configuration becomes invalid, or that the interpretation changes. | ||
|
|
||
| A secondary objective is to allow for stable code generation from the JSON schema for language implementations of the [in-memory configuration model](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk.md#in-memory-configuration-model). With stability guarantees in mind, maintainers should be able to write code generation logic (or handcraft an in-memory configuration model) without risk that allowed changes to the schema will break stable implementations. **NOTE**: There is _no_ guarantee that the output of off-the-shelf [code generation](#code-generation) tools will be stable when allowed changes are made. Maintainers are responsible for understanding how code generation tools work (and evolve) and intersect with the guarantees made here. |
There was a problem hiding this comment.
This secondary objective seems much like it is already a part of the primary objective. If we do not want to have users upgrade and have their configuration interpretation change we need to ensure the code that is generated, and ultimately creates their SDK, remains consistently stable.
I'm not sure we can make that guarantee though. I seems like it is going to be up to the implementations to ensure this stability when they generate the code.
Is it enough to say we do not plan to break backwards compatibility of the configuration itself and that we will follow the guidelines listed below to ensure implementations do not break. But it is the responsibility of the implementation to comply with their language specific stability requirements?
There was a problem hiding this comment.
I'm not sure we can make that guarantee though. I seems like it is going to be up to the implementations to ensure this stability when they generate the code.
I'm not sure we can make that guarantee though. I seems like it is going to be up to the implementations to ensure this stability when they generate the code.
Is it enough to say we do not plan to break backwards compatibility of the configuration itself and that we will follow the guidelines listed below to ensure implementations do not break. But it is the responsibility of the implementation to comply with their language specific stability requirements?
Yes and yes. I've updated the phrasing so that there is one objective: allow users to reliably upgrade minor versions without risk that there configuration becomes invalid or interpretation changes.
I still kept some of the color commentary here, especially to inform maintainers that they need to evaluate these guarantees when considering the in-memory configuration model and their respective SIG's stability guarnatees.
Let me know what you think.
|
Resolving my own comments to start a fresh review. |
…y-configuration into stability-definition
|
Curious if other reviewers @marcalff, @codeboten, @carlosalberto are planning on picking this back up. In the config SIG, we discussed how it will be important to land something specifying stability requirements so we have a chance to evaluate changes through the context of the requirements and have the chance to iterate / improve. Best case would have had these requirements in place 6-12 months. But next best time is now, while there are still a handful of modeling decisions to be made before stability. If you don't have time to pick this back up soon, do you feel comfortable with this language as a starting point? |
codeboten
left a comment
codeboten
left a comment
There was a problem hiding this comment.
The language looks ok to me, thanks for addressing my comments
…y-configuration into stability-definition
|
Merging because the "Validator Tests / Push Docker image to Docker Hub" failure is unrelated. Opened #178 to track. |
5 participants
Related to #2.
Resolves #89.
Took inspiration from prior art in the opentelemetry-proto stability definition, but adapted for a variety of differences in the the domains of OTLP vs. declarative configuration, protobuf vs. JSON schema.