search

open-telemetry / opentelemetry.io

The OpenTelemetry website and documentation
https://opentelemetry.io
Creative Commons Attribution 4.0 International
517 stars 1.1k forks source link

Page feedback on schema definitions. #4892

Open PaulRashidi opened 1 month ago

PaulRashidi commented 1 month ago

Suggested improvements for page: https://opentelemetry.io/docs/specs/otel/schemas/file_format_v1.1.0/#appendix-a-example-schema-file

Could you provide a way to diff between 1.0.0 and 1.1.0 as well as future versions.

If you just provided the a GitHub link on the actual spec file using commit hashes to delineate each version that would suffice. Even if the link pointed at a diff of the documentation page if it contained the changes (though you might have to use tags in that case to escape inception).

It would also be nice if the "Development" note had some context like when got to that state or when it might change so we can understand how stale it is. Since this state allows for breaking changes and there isn't a stable Schema document it implies Schemas are sort of experimental, but I don't think that is actually the case.

svrnm commented 1 month ago

Hey @PaulRashidi, thanks for raising this issue! This page is sourced from the spec repository (file is https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/file_format_v1.1.0.md), so would you mind raising this issue there or me transferring your issue?

cartermp commented 1 month ago

I think this opens up an interesting question about supporting versions of the spec that you can toggle around between. For most uses that wouldn't be terribly helpful, but for this in particular in would be.