chore(semantic-conventions): docs on entry-points, deprecations; improve some deprecation messages

[trentm]

This adds a few things to the readme: more intro content, notes on using the "incubating" entry-point, a section clarifying the various deprecations and how to upgrade.

This also tweaks the @deprecated messages in the old usage forms, mainly to add a link to the README section on the "incubating" entry-point when the suggested new constant is only in the incubating entry-point.

Closes: #5025

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 94.56%. Comparing base (0ee9a27) to head (859f2d2).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5166      +/-   ##
==========================================
- Coverage   94.57%   94.56%   -0.02%     
==========================================
  Files         314      314              
  Lines        7961     7961              
  Branches     1600     1600              
==========================================
- Hits         7529     7528       -1     
- Misses        432      433       +1     

see 1 file with indirect coverage changes

---- 🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests
• JS Bundle Analysis - Avoid shipping oversized bundles

[dyladan]

Looks good to me. Too bad we caused such confusion with the deprecations but i think the package overall is better with the changes.

[JamieDanielson]

Added a few notes for the guidelines. Thank you for working on this!

[trentm]

@JamieDanielson pointed out that copying definitions for unstable semconv constants is recommended: https://opentelemetry.io/docs/specs/semconv/non-normative/code-generation/#stability-and-versioning
I'd known that Java was recommending this, but hadn't realized that suggestion made it into the (granted "non-normative") part of the spec.

I've added that as an option alternative to depending on a pinned version and using the "incubating" entry point.
However, do you think we should reverse the suggestion and have the first suggestion be copying the definitions?
(This could be done in a separate PR.)

[JamieDanielson]

I've added that as an option alternative to depending on a pinned version and using the "incubating" entry point. However, do you think we should reverse the suggestion and have the first suggestion be copying the definitions? (This could be done in a separate PR.)

Thinking through this more... while it may not be a big deal for someone to pin now when only http is stable, it will become a bigger issue when the next wave of stable attributes come through (if there are changes). This would mean folks have the option to either pin and miss out on new stable attributes, or unpin and risk breaking changes. I'm leaning even more heavily now toward copying attributes, but am fine with that as a follow-up.

[trentm]

I'm leaning even more heavily now toward copying attributes, but am fine with that as a follow-up.

Moved to #5182