Clarify current stability guarantees #406
Conversation
tigrannajaryan
force-pushed
the
feature/tigran/stability
branch
2 times, most recently
from
c571264 to
c31c4ae
Compare
tigrannajaryan
force-pushed
the
feature/tigran/stability
branch
from
c31c4ae to
dd74cc5
Compare
@bogdandrutu I have this in the text: Are you looking for more? |
| 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. |
There was a problem hiding this comment.
Is the "optional" attribute considered part of the type?
| - Message names may change. | ||
| - Field names may change. | ||
| - Enum names may change. | ||
| - Enum choice names may change. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
It is possible, numbers already assigned cannot be reassigned or changed
| - Service names and service package names will not change. | ||
| - Service operation names, parameter and return types will not change. | ||
|
|
||
| The following changes are allowed: |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| - 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. |
There was a problem hiding this comment.
What does "service package name" mean?
There was a problem hiding this comment.
The package name where the service is declared, e.g.:
tigrannajaryan
force-pushed
the
feature/tigran/stability
branch
from
dd74cc5 to
2bf5ddc
Compare
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.
tigrannajaryan
force-pushed
the
feature/tigran/stability
branch
from
2bf5ddc to
d84f877
Compare
|
I am merging this since I believe it is an improvement over the current state. If further improvements are desirable please submit new PRs. |
This PR captures the current understanding of stability guarnatees.
I want to make sure it is explicitly visible until we make a decision
on #400
The most likely outcome of #400
is going to be stronger than current definition of "Stable.