docs(instrumentation): better docs for supportedVersions option (#4693)

* docs(instrumentation): better docs for supportedVersions option * docs: add recomundation to bound major version * revert: Instrumentation class changes * docs: add recommendation in both places * docs: lint fix * chore: CHANGLOG * Update experimental/packages/opentelemetry-instrumentation/src/types.ts * Update experimental/packages/opentelemetry-instrumentation/src/types.ts --------- Co-authored-by: Marc Pichler <[email protected]>
open-telemetry · May 13, 2024 · 50bd460 · 50bd460
1 parent 1c6e8b2
commit 50bd460
Show file tree

Hide file tree

Showing 2 changed files with 27 additions and 2 deletions.
diff --git a/experimental/CHANGELOG.md b/experimental/CHANGELOG.md
@@ -31,6 +31,7 @@ All notable changes to experimental packages in this project will be documented
 
 ### :books: (Refine Doc)
 
+* docs(instrumentation): better docs for supportedVersions option [#4693](https://github.com/open-telemetry/opentelemetry-js/pull/4693) @blumamir
 * docs: align all supported versions to a common format [#4696](https://github.com/open-telemetry/opentelemetry-js/pull/4696) @blumamir
 
 ### :house: (Internal)

diff --git a/experimental/packages/opentelemetry-instrumentation/src/types.ts b/experimental/packages/opentelemetry-instrumentation/src/types.ts
@@ -88,7 +88,19 @@ export interface InstrumentationModuleFile {
 
  moduleExports?: unknown;
 
- /** Supported version this file */
+ /** Supported versions for the file.
+ *
+ * A module version is supported if one of the supportedVersions in the array satisfies the module version.
+ * The syntax of the version is checked with the `satisfies` function of "The semantic versioner for npm", see
+ * [`semver` package](https://www.npmjs.com/package/semver)
+ * If the version is not supported, we won't apply instrumentation patch.
+ * If omitted, all versions of the module will be patched.
+ *
+ * It is recommended to always specify a range that is bound to a major version, to avoid breaking changes.
+ * New major versions should be reviewed and tested before being added to the supportedVersions array.
+ *
+ * Example: ['>=1.2.3 <3']
+ */
  supportedVersions: string[];
 
  /** Method to patch the instrumentation */
@@ -108,7 +120,19 @@ export interface InstrumentationModuleDefinition {
  /** Instrumented module version */
  moduleVersion?: string;
 
- /** Supported version of module */
+ /** Supported version of module.
+ *
+ * A module version is supported if one of the supportedVersions in the array satisfies the module version.
+ * The syntax of the version is checked with the `satisfies` function of "The semantic versioner for npm", see
+ * [`semver` package](https://www.npmjs.com/package/semver)
+ * If the version is not supported, we won't apply instrumentation patch (see `enable` method).
+ * If omitted, all versions of the module will be patched.
+ *
+ * It is recommended to always specify a range that is bound to a major version, to avoid breaking changes.
+ * New major versions should be reviewed and tested before being added to the supportedVersions array.
+ *
+ * Example: ['>=1.2.3 <3']
+ */
  supportedVersions: string[];
 
  /** Module internal files to be patched */