Proposal: move OTLP spec to github.com/open-telemetry/opentelemetry-proto

[tigrannajaryan]

The protocol specification is currently split between this repo which contains the verbal description of top-level message exchanges and https://github.com/open-telemetry/opentelemetry-proto which contains the Protobuf definitions, including verbal description of many fields.

This split is unnecessary and makes reading and understanding the entire OTLP protocol more difficult than it needs to be.

I suggest to move the following files to https://github.com/open-telemetry/opentelemetry-proto:

specification/protocol/README.md
specification/protocol/design-goals.md
specification/protocol/otlp.md
specification/protocol/requirements.md

We have a similar co-location of spec text and proto files for OpAMP and it worked well for the workgroup.

[tigrannajaryan]

@open-telemetry/specs-approvers please comment.

[yurishkuro]

+1

[jack-berg]

What can we do to keep the OTLP specification documents discoverable? Its definitely easier to find the OTLP specification than it is the OpAmp specification for a casual user. Can we keep a placeholder in the specification repo which links to the proto repository?

[tigrannajaryan]

What can we do to keep the OTLP specification documents discoverable? Its definitely easier to find the OTLP specification than it is the OpAmp specification for a casual user. Can we keep a placeholder in the specification repo which links to the proto repository?

Yes, that's what I want to do. I will not delete the docs from spec repo. I will keep the docs, but will replace the content with links to the new location. This will also ensure any existing external links to the docs will not become 404 after the move.

[chalin]

What can we do to keep the OTLP specification documents discoverable?

Since the OTLP spec will be published via the OTel website, the options of which are discussed in open-telemetry/opentelemetry.io#2642 (comment), I'd propose that discoverability be via the website, and that we avoid keeping a copy of the pages (even if only redirect links), in the OTel spec repo. WDYT?

/cc @svrnm @cartermp

[tigrannajaryan]

I'd propose that discoverability be via the website, and that we avoid keeping a copy of the pages (even if only redirect links), in the OTel spec repo. WDYT?

I would still prefer to keep the spec repo files (with content deleted and just referring the reader to the new location). I have seen countless examples of people linking directly to files in spec repo. These links will all become 404 if we delete the files.

[bogdandrutu]

+1