docs: documentation on versioning

[rauno56]

Which problem is this PR solving?

This actually an issue in a PR form to

• explain my understanding of what happenend with the versioning breakage in contrib;
• to allow for better comments and updating the situation as we go with the history;
• to grow that into a guide of some sort for contributors in core as well as contrib.

Short description of the changes

Currently just a description for what happened and why + couple of my personal takes for solutions for feedback and critisism.

Read the file stylized for more confortable reading here.

[codecov]

Codecov Report

Merging #2863 (b65d87e) into main (549bd5b) will increase coverage by 0.32%.
The diff coverage is n/a.

❗ Current head b65d87e differs from pull request most recent head f171700. Consider uploading reports for the commit f171700 to get more accurate results

@@            Coverage Diff             @@
##             main    #2863      +/-   ##
==========================================
+ Coverage   93.19%   93.52%   +0.32%     
==========================================
  Files         157      163       +6     
  Lines        5117     5572     +455     
  Branches     1097     1180      +83     
==========================================
+ Hits         4769     5211     +442     
- Misses        348      361      +13     

Impacted Files	Coverage Δ
...-instrumentation-fetch/src/enums/AttributeNames.ts	100.00% <0.00%> (ø)
...exporter-metrics-otlp-http/src/transformMetrics.ts	95.65% <0.00%> (ø)
...s/opentelemetry-instrumentation-fetch/src/fetch.ts	97.00% <0.00%> (ø)
...ation-xml-http-request/src/enums/AttributeNames.ts	100.00% <0.00%> (ø)
...emetry-instrumentation-xml-http-request/src/xhr.ts	97.57% <0.00%> (ø)
...mentation-xml-http-request/src/enums/EventNames.ts	100.00% <0.00%> (ø)

[rauno56]

My comments are clearly in conflict with what the spec intends the stability guarantees to be.
See: open-telemetry/opentelemetry-specification#1452 (comment)

However, my arguments are coming from the point of view of how node ecosystem works and operates. We should still look for a solid way to avoid such problems for our users even if The Spec doesn't specify how we should do that.

[dyladan]

This is specifically contrary to the versioning document in the spec which states that the semver guarantees do not apply to SDK implementors. SDK implementors should consider minor semver updates to the API to be breaking. The semver version of the API should only make a major change if it affects API callers not implementers.

[Flarna]

I think one of the important topics is to avoid duplication of modules. NPM dedup seems to behave different between major versions. I'm not 100% sure but I think the dedup differs also between modules mentioned in dependencies and the automatic installed peer dependencies.

I think the main problem we have regarding version ranges are that serveral modules implement an interface from another module. For them a semver minor update can be breaking. e.g.

• SDK implement API
• propagators implement parts of API
• context managers implement parts of API
• Exporters/SpanProcessors implement parts of the SDK API

Besides the pure JS compatibility there is also the typescript compatibility. see e.g. #2845
The cause is by using the class Span in interface SpanProcessor.

The type system tells here that classes - even with the same name and shape - do not match if they come from different .d.ts files. So if dedup is not working for whatever reason users may end up in such problems even the JS code would work fine.

The solution for this would be to never use a class in APIs instead use an interface. For above case I started this here but I noticed that this is not that simple as class Span refers to other classes like Resource.
I assume fixing this in all OTel modules is quite some work and most likely breaking. Besides that some tooling would be nice to avoid that classes are exported by accident. Not sure if classes are the only issue here.

[github-actions]

This PR is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 14 days.

[github-actions]

This PR was closed because it has been stale for 14 days with no activity.