doc(semantic-conventions): clarify suggested usage of *unstable* semconv

It is recommended that users (typically instrumentation libraries) of *unstable*
semconv create a local copy of relevant definitions, rather than pinning.
Pinning of this package can easily lead to very many versions of the package
being installed, which leads to heavy disk usage.

Refs: open-telemetry#5182

semantic-conventions/CHANGELOG.md

@@ -13,6 +13,8 @@ All notable changes to the semantic-conventions package will be documented in th
 
 ### :books: (Refine Doc)
 
+* docs: Document suggested usage of unstable semconv: copy relevant definitions into your code base.
+
 ### :house: (Internal)
 
 ## 1.28.0

semantic-conventions/README.md

@@ -18,7 +18,7 @@ This package has 2 separate entry-points:
 - The main entry-point, `@opentelemetry/semantic-conventions`, includes only stable semantic conventions.
   This entry-point follows semantic versioning 2.0: it will not include breaking changes except with a change in the major version number.
 - The "incubating" entry-point, `@opentelemetry/semantic-conventions/incubating`, contains unstable semantic conventions (sometimes called "experimental") and, for convenience, a re-export of the stable semantic conventions.
-  This entry-point is _NOT_ subject to the restrictions of semantic versioning and _MAY_ contain breaking changes in minor releases.
+  This entry-point is _NOT_ subject to the restrictions of semantic versioning and _MAY_ contain breaking changes in minor releases. See below for suggested usage of this entry-point.
 
 Exported constants follow this naming scheme:
 
@@ -59,30 +59,51 @@ const span = tracer.startSpan(spanName, spanOptions)
 
 <!-- Dev Note: ^^ This '#unstable-semconv' anchor is being used in jsdoc links in the code. -->
 
-```bash
-npm install --save-exact @opentelemetry/semantic-conventions
-```
+Because the "incubating" entry-point may include breaking changes in minor versions, it is recommended that instrumentation libraries **not** import `@opentelemetry/semantic-conventions/incubating` in runtime code, but instead **copy relevant definitions into their own code base**. (This is the same [recommendation](https://opentelemetry.io/docs/specs/semconv/non-normative/code-generation/#stability-and-versioning) as for other languages.)
 
-**Note**: Because the "incubating" entry-point may include breaking changes in minor versions, it is recommended that users of unstable semconv values either:
+For example, create a "src/semconv.ts" (or "lib/semconv.js" if implementing in JavaScript) file that copies from [experimental_attributes.ts](./src/experimental_attributes.ts) or [experimental_metrics.ts](./src/experimental_metrics.ts):
 
-1. depend on a pinned (exact) version of the package (`npm install --save-exact ...`), or
-2. [copy relevant definitions to their code base](https://opentelemetry.io/docs/specs/semconv/non-normative/code-generation/#stability-and-versioning).
+```ts
+// src/semconv.ts
+export const ATTR_DB_NAMESPACE = 'db.namespace';
+export const ATTR_DB_OPERATION_NAME = 'db.operation.name';
+```
 
 ```ts
+// src/instrumentation.ts
+import {
+  ATTR_SERVER_PORT,
+  ATTR_SERVER_ADDRESS,
+} from '@opentelemetry/semantic-conventions';
 import {
-  ATTR_PROCESS_COMMAND,
-  ATTR_PROCESS_COMMAND_ARGS,
-  ATTR_PROCESS_COMMAND_LINE,
-} from '@opentelemetry/semantic-conventions/incubating';
+  ATTR_DB_NAMESPACE,
+  ATTR_DB_OPERATION_NAME,
+} from './semconv';
+
+span.setAttributes({
+  [ATTR_DB_NAMESPACE]: ...,
+  [ATTR_DB_OPERATION_NAME]: ...,
+  [ATTR_SERVER_PORT]: ...,
+  [ATTR_SERVER_ADDRESS]: ...,
+})
+```
 
-const span = tracer.startSpan(spanName, spanOptions)
-  .setAttributes({
-    [ATTR_PROCESS_COMMAND]: 'cat',
-    [ATTR_PROCESS_COMMAND_ARGS]: ['file1', 'file2'],
-    [ATTR_CONTAINER_COMMAND_LINE]: 'cat file1 file2',
-  });
+Occasionally, one should review changes to `@opentelemetry/semantic-conventions` to see if any used unstable conventions have changed or been stabilized. However, an update to a newer minor version of the package will never be breaking.
+
+#### Why not pin the version?
+
+A considered alternative for using unstable exports is to **pin** the version. I.e., depend on an exact version, rather than on a version range.
+
+```bash
+npm install --save-exact @opentelemetry/semantic-conventions
 ```
 
+Then, import directly from `@opentelemetry/semantic-conventions/incubating`.
+This is **not** recommended.
+
+In some languages having multiple versions of a package in a single application is not possible. This *is* possible in JavaScript. The primary argument against pinning this package is that it can easily lead to many copies being installed in an application's `node_modules/...`, which can cause significant disk usage. In a disk-constrained environment, such as AWS Lambda Layers, that can be a blocker.
+
+
 ## Deprecations
 
 There are two main types of deprecations in this package:
@@ -153,16 +174,26 @@ See [Migrated usage](#migrated-usage) below.
 
 ### Migrated usage
 
+If using any unstable conventions, copy the relevant definitions into your code base (e.g. to "src/semconv.ts", see [above](#unstable-semconv)):
+
+```ts
+// src/semconv.ts
+export const ATTR_DB_SYSTEM = 'db.system' as const;
+export const DB_SYSTEM_VALUE_POSTGRESQL = "postgresql" as const;
+```
+
+then:
+
 ```js
 import {
   ATTR_SERVICE_NAME,
   ATTR_HTTP_ROUTE,
   METRIC_HTTP_CLIENT_REQUEST_DURATION
-} from '@opentelemetry/semantic-conventions';
+} from '@opentelemetry/semantic-conventions'; // stable semconv
 import {
   ATTR_DB_SYSTEM,
   DB_SYSTEM_VALUE_POSTGRESQL
-} from '@opentelemetry/semantic-conventions/incubating';
+} from './semconv'; // unstable semconv
 
 console.log(ATTR_SERVICE_NAME); // 'service.name'
 console.log(ATTR_HTTP_ROUTE);   // 'http.route'
@@ -176,13 +207,6 @@ console.log(ATTR_DB_SYSTEM);    // 'db.system'
 console.log(DB_SYSTEM_VALUE_POSTGRESQL);
 ```
 
-### What is "incubating"?
-
-The first three fields in the preceding code sample ('service.name', 'http.route', 'http.client.request.duration') are _stable_ in semantic conventions, the latter two are not. Version 1.26.0 of this package separated stable and unstable into separate module entry points: stable conventions are imported `from '@opentelemetry/semantic-conventions'` and unstable `from '@opentelemetry/semantic-conventions/incubating'`. The name "incubating" is [suggested by the Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/non-normative/code-generation/#semantic-conventions-artifact-structure).
-
-It is recommended that if you are using exports from _incubating_, that you **pin the version** in your package.json dependencies (e.g. via `npm install --save-exact @opentelemetry/semantic-conventions`) _or_ that you copy the relevant definitions into your code base. This is because the removal of exports from the _incubating_ entry point is _not considered a breaking change_ and hence can happen in a minor version.
-
-Note: The _incubating_ entry point also exports all stable fields, so the above example could be changed to import all five constants `from '@opentelemetry/semantic-conventions/incubating'`.
 
 ## Useful links