From 5b5195a6d33e55dc102d7e4dd308de1cfeb6e67f Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Fri, 10 May 2024 09:38:52 +0300 Subject: [PATCH 1/8] docs(instrumentation): better docs for supportedVersions option --- .../src/types.ts | 22 +++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/experimental/packages/opentelemetry-instrumentation/src/types.ts b/experimental/packages/opentelemetry-instrumentation/src/types.ts index 3adc03921df..074078efaee 100644 --- a/experimental/packages/opentelemetry-instrumentation/src/types.ts +++ b/experimental/packages/opentelemetry-instrumentation/src/types.ts @@ -96,7 +96,16 @@ 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 ot 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. + * + * Example: ['>=1.2.3 <3'] + */ supportedVersions: string[]; /** Method to patch the instrumentation */ @@ -118,7 +127,16 @@ 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 ot 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. + * + * Example: ['>=1.2.3 <3'] + */ supportedVersions: string[]; /** Module internal files to be patched */ From 1f3e883c499141598b4defeded88daf1ae3aafc8 Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Fri, 10 May 2024 09:51:45 +0300 Subject: [PATCH 2/8] docs: add recomundation to bound major version --- .../opentelemetry-instrumentation/src/types.ts | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/experimental/packages/opentelemetry-instrumentation/src/types.ts b/experimental/packages/opentelemetry-instrumentation/src/types.ts index 074078efaee..c56e54d9d1f 100644 --- a/experimental/packages/opentelemetry-instrumentation/src/types.ts +++ b/experimental/packages/opentelemetry-instrumentation/src/types.ts @@ -60,7 +60,12 @@ export interface Instrumentation< * All versions must be compatible with [semver](https://semver.org/spec/v2.0.0.html) format. * 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[]; } @@ -135,6 +140,9 @@ export interface InstrumentationModuleDefinition { * 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[]; From e4707abad18f40754a63eb1d4c8fda6d960979f5 Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Fri, 10 May 2024 09:52:43 +0300 Subject: [PATCH 3/8] revert: Instrumentation class changes --- .../packages/opentelemetry-instrumentation/src/types.ts | 5 ----- 1 file changed, 5 deletions(-) diff --git a/experimental/packages/opentelemetry-instrumentation/src/types.ts b/experimental/packages/opentelemetry-instrumentation/src/types.ts index c56e54d9d1f..2c05efa6657 100644 --- a/experimental/packages/opentelemetry-instrumentation/src/types.ts +++ b/experimental/packages/opentelemetry-instrumentation/src/types.ts @@ -60,11 +60,6 @@ export interface Instrumentation< * All versions must be compatible with [semver](https://semver.org/spec/v2.0.0.html) format. * 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[]; } From eb7229b8c547ce8bf94ef531b53c72b05b4f4016 Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Fri, 10 May 2024 09:54:30 +0300 Subject: [PATCH 4/8] docs: add recommendation in both places --- .../packages/opentelemetry-instrumentation/src/types.ts | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/experimental/packages/opentelemetry-instrumentation/src/types.ts b/experimental/packages/opentelemetry-instrumentation/src/types.ts index 2c05efa6657..9adb32df8a0 100644 --- a/experimental/packages/opentelemetry-instrumentation/src/types.ts +++ b/experimental/packages/opentelemetry-instrumentation/src/types.ts @@ -60,7 +60,7 @@ export interface Instrumentation< * All versions must be compatible with [semver](https://semver.org/spec/v2.0.0.html) format. * 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. - */ + */ supportedVersions?: string[]; } @@ -104,8 +104,11 @@ export interface InstrumentationModuleFile { * 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 */ @@ -139,7 +142,7 @@ export interface InstrumentationModuleDefinition { * 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 */ From da017e981ef61b29d004ad13974292196e4519f4 Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Fri, 10 May 2024 09:55:21 +0300 Subject: [PATCH 5/8] docs: lint fix --- .../opentelemetry-instrumentation/src/types.ts | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/experimental/packages/opentelemetry-instrumentation/src/types.ts b/experimental/packages/opentelemetry-instrumentation/src/types.ts index 9adb32df8a0..0336d5fb398 100644 --- a/experimental/packages/opentelemetry-instrumentation/src/types.ts +++ b/experimental/packages/opentelemetry-instrumentation/src/types.ts @@ -97,16 +97,16 @@ export interface InstrumentationModuleFile { moduleExports?: unknown; /** Supported versions for the file. - * + * * A module version is supported if one of the supportedVersions in the array satisfies the module version. - * The syntax ot the version is checked with the `satisfies` function of "The semantic versioner for npm", see + * The syntax ot 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[]; @@ -131,16 +131,16 @@ export interface InstrumentationModuleDefinition { moduleVersion?: string; /** Supported version of module. - * + * * A module version is supported if one of the supportedVersions in the array satisfies the module version. - * The syntax ot the version is checked with the `satisfies` function of "The semantic versioner for npm", see + * The syntax ot 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[]; From 13466573b01ad7fbd10b4b7daca8dd88e6ca47aa Mon Sep 17 00:00:00 2001 From: Amir Blum Date: Fri, 10 May 2024 10:06:19 +0300 Subject: [PATCH 6/8] chore: CHANGLOG --- experimental/CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/experimental/CHANGELOG.md b/experimental/CHANGELOG.md index 20e3fbfdab3..674aed2f562 100644 --- a/experimental/CHANGELOG.md +++ b/experimental/CHANGELOG.md @@ -29,6 +29,8 @@ 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 + ### :house: (Internal) ## 0.51.0 From b76698bfdf51e71bdf7df3290a0bbe460f473464 Mon Sep 17 00:00:00 2001 From: Marc Pichler Date: Mon, 13 May 2024 10:59:00 +0200 Subject: [PATCH 7/8] Update experimental/packages/opentelemetry-instrumentation/src/types.ts --- .../packages/opentelemetry-instrumentation/src/types.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/experimental/packages/opentelemetry-instrumentation/src/types.ts b/experimental/packages/opentelemetry-instrumentation/src/types.ts index 0336d5fb398..38083048c54 100644 --- a/experimental/packages/opentelemetry-instrumentation/src/types.ts +++ b/experimental/packages/opentelemetry-instrumentation/src/types.ts @@ -133,7 +133,7 @@ export interface InstrumentationModuleDefinition { /** Supported version of module. * * A module version is supported if one of the supportedVersions in the array satisfies the module version. - * The syntax ot the version is checked with the `satisfies` function of "The semantic versioner for npm", see + * 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. From 687fb84c9ef572e353764634a7d91b3a3b51c9ae Mon Sep 17 00:00:00 2001 From: Marc Pichler Date: Mon, 13 May 2024 10:59:04 +0200 Subject: [PATCH 8/8] Update experimental/packages/opentelemetry-instrumentation/src/types.ts --- .../packages/opentelemetry-instrumentation/src/types.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/experimental/packages/opentelemetry-instrumentation/src/types.ts b/experimental/packages/opentelemetry-instrumentation/src/types.ts index 38083048c54..3eb206197b0 100644 --- a/experimental/packages/opentelemetry-instrumentation/src/types.ts +++ b/experimental/packages/opentelemetry-instrumentation/src/types.ts @@ -99,7 +99,7 @@ export interface InstrumentationModuleFile { /** Supported versions for the file. * * A module version is supported if one of the supportedVersions in the array satisfies the module version. - * The syntax ot the version is checked with the `satisfies` function of "The semantic versioner for npm", see + * 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.