docs(instrumentation): better docs for supportedVersions option (open-telemetry#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]>

Author: 2 people

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)

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  */