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.

Sign up for GitHub

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

Define OpAMP Protobuf schema stability guarantees #141

Merged
merged 1 commit into from
May 30, 2023
Merged

Define OpAMP Protobuf schema stability guarantees #141

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
26 changes: 26 additions & 0 deletions specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,7 @@ Note: this document requires a simplification pass to reduce the scope, size and
* [Interoperability of Future Capabilities](#interoperability-of-future-capabilities)
+ [Ignorable Capability Extensions](#ignorable-capability-extensions)
+ [Non-Ignorable Capability Extensions](#non-ignorable-capability-extensions)
+ [Protobuf Schema Stability](#protobuf-schema-stability)
- [Performance and Scale](#performance-and-scale)
- [FAQ for Reviewers](#faq-for-reviewers)
* [What is WebSocket?](#what-is-websocket)
Expand Down Expand Up @@ -2571,6 +2572,31 @@ peer and adjust their behavior appropriately. How exactly the behavior is
adjusted for future capabilities MUST be defined in the future specification of
the new capabilities.

### Protobuf Schema Stability

The specification provides the follow stability guarantees of the
[Protobuf definitions](proto/opamp.proto) for OpAMP 1.0:

- Field types, numbers and names will not change.
- Names of messages and enums will not change.
- Numbers assigned to enum choices will not change.
- Names of enum choices will not change.
- The location of messages and enums, i.e. whether they are declared at the top lexical
scope or nested inside another message will not change.
- Package names and directory structure will not change.
- `optional` and `repeated` declarators of existing fields will not change.
tigrannajaryan marked this conversation as resolved.
Show resolved Hide resolved
- No existing symbol will be deleted.

Future versions of the OpAMP specification may be extended by modifying the
Protobuf schema defined in this specification version. The following Protobuf schema
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we specify how deprecations will be handled for the spec?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I haven't put anything thought into the subject of deprecations. I also don't see anything in OTLP spec to use as an inspiration. It is probably worth thinking about, but probably should be a separate PR.

changes are allowed, provided that they comply with the interoperability requirements
defined elsewhere in this specification:

- Adding new fields to existing messages.
- Adding new messages or enums.
- Adding new choices to existing enums.
- Adding new choices to existing oneof fields.

# Performance and Scale

TBD
Expand Down