docs: shorten readme sections (#4460)

Co-authored-by: Marc Pichler <marc.pichler@dynatrace.com>
open-telemetry · Feb 6, 2024 · f86251d · f86251d
1 parent 63845ec
commit f86251d
Show file tree

Hide file tree

Showing 7 changed files with 291 additions and 284 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -24,6 +24,8 @@ For experimental package changes, see the [experimental CHANGELOG](experimental/
 
 ### :books: (Refine Doc)
 
+* docs: shorten readme sections [#4460](https://github.com/open-telemetry/opentelemetry-js/pull/4460) @legendecas
+
 ### :house: (Internal)
 
 ## 1.21.0

diff --git a/README.md b/README.md
@@ -149,24 +149,33 @@ The below table describes which versions of each set of packages are expected to
 | 1.19.x                                                          | 0.46.x                |
 | 1.18.x                                                          | 0.45.x                |
 | 1.17.x                                                          | 0.44.x                |
-| 1.16.x                                                          | 0.42.x                |
-| 1.15.x                                                          | 0.41.x                |
-| 1.14.x                                                          | 0.40.x                |
-| 1.13.x                                                          | 0.39.x                |
-| 1.12.x                                                          | 0.38.x                |
-| 1.11.x                                                          | 0.37.x                |
-| 1.10.x                                                          | 0.36.x                |
-| 1.9.x                                                           | 0.35.x                |
-| 1.8.x (this and later versions require API >=1.3.0 for metrics) | 0.34.x                |
-| 1.7.x                                                           | 0.33.x                |
-| 1.6.x                                                           | 0.32.x                |
-| 1.5.x                                                           | 0.31.x                |
-| 1.4.x                                                           | 0.30.x                |
-| 1.3.x                                                           | 0.29.x                |
-| 1.2.x                                                           | 0.29.x                |
-| 1.1.x                                                           | 0.28.x                |
-| 1.0.x                                                           | 0.27.x                |
-| 1.0.x (this and later versions require API >=1.0.0 for traces)  | 0.26.x                |
+
+<details>
+<summary>Older version compatibility matrix</summary>
+
+<table>
+<tr><th>Stable Packages</th>                            <th>Experimental Packages</th></tr>
+<tr><td>1.16.x</td>                                                    <td>0.42.x</td></tr>
+<tr><td>1.15.x</td>                                                    <td>0.41.x</td></tr>
+<tr><td>1.14.x</td>                                                    <td>0.40.x</td></tr>
+<tr><td>1.13.x</td>                                                    <td>0.39.x</td></tr>
+<tr><td>1.12.x</td>                                                    <td>0.38.x</td></tr>
+<tr><td>1.11.x</td>                                                    <td>0.37.x</td></tr>
+<tr><td>1.10.x</td>                                                    <td>0.36.x</td></tr>
+<tr><td>1.9.x</td>                                                     <td>0.35.x</td></tr>
+<tr><td>1.8.x (this and later versions require API >=1.3.0 for metrics)</td><td>0.34.x</td></tr>
+<tr><td>1.7.x</td>                                                     <td>0.33.x</td></tr>
+<tr><td>1.6.x</td>                                                     <td>0.32.x</td></tr>
+<tr><td>1.5.x</td>                                                     <td>0.31.x</td></tr>
+<tr><td>1.4.x</td>                                                     <td>0.30.x</td></tr>
+<tr><td>1.3.x</td>                                                     <td>0.29.x</td></tr>
+<tr><td>1.2.x</td>                                                     <td>0.29.x</td></tr>
+<tr><td>1.1.x</td>                                                     <td>0.28.x</td></tr>
+<tr><td>1.0.x</td>                                                     <td>0.27.x</td></tr>
+<tr><td>1.0.x (this and later versions require API >=1.0.0 for traces)</td><td>0.26.x</td></tr>
+</table>
+
+</details>
 
 ## Versioning
 
@@ -299,266 +308,9 @@ These instrumentations are hosted at <https://github.com/open-telemetry/opentele
 | -------------------------------------------------------- | --------------------------------------------------------------------------------------- |
 | [@opentelemetry/shim-opentracing][otel-shim-opentracing] | OpenTracing shim allows existing OpenTracing instrumentation to report to OpenTelemetry |
 
-## Upgrade guidelines
-
-### 0.37.x to 0.38.0
-
-- `@opentelemetry/sdk-node` `NodeSDKConfiguration.defaultAttributes` has been unused and was removed as the concept does not exist in OpenTelemetry anymore
-  - Please use `NodeSDKConfiguration.resource` instead.
-
-### 0.35.x to 0.36.0
-
-- `@opentelemetry/sdk-node` changed `await start()` to now be synchronous
-- `@opentelemetry/sdk-node` changed `await detectResources()` to now be synchronous
-
-### 0.28.x to 0.29.x
-
-- `@opentelemetry/exporter-trace-otlp-http` is now exporting `scopeSpans` instead of `instrumentationLibrarySpans`
-  - this exporter now requires collector version `0.48` and up.
-- `@opentelemetry/exporter-metrics-otlp-http` is now exporting `scopeMetrics` instead of `instrumentationLibraryMetrics`
-  - this exporter now requires collector version `0.48` and up.
-
-### 0.27.x to 0.28.x
-
-- In `@opentelemetry/exporter-trace-otlp-http`, `OTLPExporterBase._isShutdown` is replaced with `_shutdownOnce`.
-
-### 0.26.x to 0.27.x
-
-Metric and trace exporters are split into separate packages:
-
-- `@opentelemetry/exporter-otlp-http` => `@opentelemetry/exporter-trace-otlp-http` and `@opentelemetry/exporter-metrics-otlp-http`
-- `@opentelemetry/exporter-otlp-grpc` => `@opentelemetry/exporter-trace-otlp-grpc` and `@opentelemetry/exporter-metrics-otlp-grpc`
-- `@opentelemetry/exporter-otlp-proto` => `@opentelemetry/exporter-trace-otlp-proto` and `@opentelemetry/exporter-metrics-otlp-proto`
-
-Metric types are renamed:
-
-- `@openetelemetry/api-metrics`
-  - `Meter`
-    - `createValueRecorder` => `createHistogram`
-    - `createValueObserver` => `createObservableGauge`
-    - `createSumObserver` => `createObservableCounter`
-    - `createUpDownSumObserver` => `createObservableUpDownCounter`
-  - `ValueRecorder` => `Histogram`
-  - `ValueObserver` => `ObservableGauge`
-  - `SumObserver` => `ObservableCounter`
-  - `UpDownSumObserver` => `ObservableUpDownCounter`
-  - `ObserverResult` => `ObservableResult`
-  - `Observation.observer` => `Observation.observable`
-- `@opentelemetry/sdk-metrics-base`
-  - `MetricKind`
-    - `VALUE_RECORDER` => `HISTOGRAM`
-    - `SUM_OBSERVER` => `OBSERVABLE_COUNTER`
-    - `UP_DOWN_SUM_OBSERVER` => `OBSERVABLE_UP_DOWN_COUNTER`
-    - `VALUE_OBSERVER` => `OBSERVABLE_GAUGE`
-
-### 0.25.x to 1.x.y
-
-Collector exporter packages and types are renamed:
-
-- `@opentelemetry/exporter-collector` => `@opentelemetry/exporter-otlp-http`
-  - `CollectorExporterBase` => `OTLPExporterBase`
-  - `CollectorTraceExporter` => `OTLPTraceExporter`
-  - `CollectorMetricExporter` => `OTLPMetricExporter`
-  - `CollectorExporterBrowserBase` => `OTLPExporterBrowserBase`
-  - `CollectorExporterNodeBase` => `OTLPExporterNodeBase`
-  - `CollectorExporterConfigBase` => `OTLPExporterConfigBase`
-  - `CollectorExporterError` => `OTLPExporterError`
-  - `COLLECTOR_SPAN_KIND_MAPPING` => `OTLP_SPAN_KIND_MAPPING`
-  - `collectorTypes` => `otlpTypes`
-- `@opentelemetry/exporter-collector-grpc` => `@opentelemetry/exporter-otlp-grpc`
-  - `CollectorTraceExporter` => `OTLPTraceExporter`
-  - `CollectorMetricExporter` => `OTLPMetricExporter`
-  - `CollectorExporterConfigNode` => `OTLPExporterConfigNode`
-- `@opentelemetry/exporter-collector-proto` => `@opentelemetry/exporter-otlp-proto`
-  - `CollectorExporterNodeBase` => `OTLPExporterNodeBase`
-  - `CollectorMetricExporter` => `OTLPMetricExporter`
-  - `CollectorTraceExporter` => `OTLPTraceExporter`
-- W3C propagators in @opentelemetry/core were renamed
-  - `HttpTraceContextPropagator` -> `W3CTraceContextPropagator`
-  - `HttpBaggagePropagator` -> `W3CBaggagePropagator`
-
-### 0.24.x to 0.25.x
-
-- SDKs packages for trace and metrics has been renamed to have a consistent naming schema:
-  - @opentelemetry/tracing -> @opentelemetry/sdk-trace-base
-  - @opentelemetry/node -> @opentelemetry/sdk-trace-node
-  - @opentelemetry/web -> @opentelemetry/sdk-trace-web
-  - @opentelemetry/metrics -> @opentelemetry/sdk-metrics-base
-  - @opentelemetry/node-sdk -> @opentelemetry/sdk-node
-
-### 0.23.x to 0.24.x
-
-- `ResourceAttributes` renamed to `SemanticResourceAttributes` in the `@opentelemetry/semantic-conventions` package
-
-### 0.19.x to 0.20.0
-
-- `HttpBaggage` renamed to `HttpBaggagePropagator`
-
-- `HttpTraceContext` renamed to `HttpTraceContextPropagator`
-
-- `JaegerHttpTracePropagator` renamed to `JaegerPropagator`
-
-- `serviceName` configuration removed from Collector exporters. Use `service.name` Resource attribute instead.
-
-- Prometheus exporter added suffix `_total` to counter metrics.
-
-### 0.18.x to 0.19.0
-
-- API is now a peer dependency. This means that users will need to include `@opentelemetry/api` as a dependency of their project in order to use the SDK. NPM version 7+ (Node 15+) should do this automatically.
-
-- All plugins have been removed in favor of instrumentations.
-
-- The `@opentelemetry/propagator-b3` package previously exported three propagators: `B3Propagator`,`B3SinglePropagator`, and `B3MultiPropagator`, but now only exports the `B3Propagator`. It extracts b3 context in single and multi-header encodings, and injects context using the single-header encoding by default, but can be configured to inject context using the multi-header endcoding during construction: `new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER })`. If you were previously using the `B3SinglePropagator` or `B3MultiPropagator` directly, you should update your code to use the `B3Propagator` with the appropriate configuration. See the [readme][otel-propagator-b3] for full details and usage.
-
-- Sampling configuration via environment variable has changed. If you were using `OTEL_SAMPLING_PROBABILITY` then you should replace it with `OTEL_TRACES_SAMPLER=parentbased_traceidratio` and `OTEL_TRACES_SAMPLER_ARG=<number>` where `<number>` is a number in the [0..1] range, e.g. "0.25". Default is 1.0 if unset.
-
-### 0.17.0 to 0.18.0
-
-- `diag.setLogLevel` is removed and LogLevel can be set by an optional second parameter to `setLogger`
-
-[PR-1975](https://github.com/open-telemetry/opentelemetry-js/pull/1975)
-
-- Breaking change - The resulting resource MUST have all attributes that are on any of the two input resources. If a key exists on both the old and updating resource, the value of the updating resource MUST be picked - previously it was opposite.
-
-### 0.16.0 to 0.17.0
-
-[PR-1880](https://github.com/open-telemetry/opentelemetry-js/pull/1880) feat(diag-logger): introduce a new global level api.diag for internal diagnostic logging
-
-[PR-1925](https://github.com/open-telemetry/opentelemetry-js/pull/1925) feat(diag-logger): part 2 - breaking changes - remove api.Logger, api.NoopLogger, core.LogLevel, core.ConsoleLogger
-
-- These PR's remove the previous `Logger` and `LogLevel` implementations and change the way you should use the replacement `DiagLogger` and `DiagLogLevel`, below are simple examples of how to change your existing usages.
-
-#### Setting the global diagnostic logger
-
-The new global [`api.diag`](https://github.com/open-telemetry/opentelemetry-js/blob/main/api/src/api/diag.ts) provides the ability to set the global diagnostic logger `setLogger()` and logging level `setLogLevel()`, it is also a `DiagLogger` implementation and should be directly to log diagnostic messages.
-
-All included logger references have been removed in preference to using the global `api.diag` directly, so you no longer need to pass around the logger instance via function parameters or included as part of the configuration for a component.
-
-```javascript
-import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
-// Setting the default Global logger to use the Console
-// And optionally change the logging level (Defaults to INFO)
-diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR)
-```
-
-#### Using the logger anywhere in the code
-
-```typescript
-import { diag } from "@opentelemetry/api";
-
-// Remove or make optional the parameter and don't use it.
-export function MyFunction() {
-  diag.debug("...");
-  diag.info("...");
-  diag.warn("...");
-  diag.error("...");
-  diag.verbose("..");
-}
-
-```
-
-#### Setting the logger back to a noop
-
-```typescript
-import { diag } from "@opentelemetry/api";
-diag.setLogger();
-
-```
-
-[PR-1855](https://github.com/open-telemetry/opentelemetry-js/pull/1855) Use instrumentation loader to load plugins and instrumentations
-
-- Providers do no load the plugins anymore. Also PluginLoader has been removed from providers, use `registerInstrumentations` instead
-
-```javascript
-//Previously in node
-const provider = new NodeTracerProvider({
-  plugins: {
-    '@grpc/grpc-js': {
-      enabled: true,
-      path: '@opentelemetry/plugin-grpc-js',
-    },
-  }
-});
-
-// Now
-const provider = new NodeTracerProvider();
-const { registerInstrumentations } = require('@opentelemetry/instrumentation');
-registerInstrumentations({
-  instrumentations: [
-    {
-      plugins: {
-        '@grpc/grpc-js': {
-          enabled: true,
-          path: '@opentelemetry/plugin-grpc-js',
-        },
-      }
-    }
-  ],
-  tracerProvider: provider,
-});
-
-// or if you want to load only default instrumentations / plugins
-registerInstrumentations({
-  tracerProvider: provider,
-});
-
-//Previously in browser
-const provider = new WebTracerProvider({
-  plugins: [
-    new DocumentLoad()
-  ]
-});
-// Now
-const { registerInstrumentations } = require('@opentelemetry/instrumentation');
-const provider = new WebTracerProvider();
-registerInstrumentations({
-  instrumentations: [
-    new DocumentLoad(),
-  ],
-});
-```
-
-- `registerInstrumentations` supports loading old plugins and instrumentations together. It also supports setting tracer provider and meter provider on instrumentations
-
-[PR-1874](https://github.com/open-telemetry/opentelemetry-js/pull/1874) More specific API type names
-
-Some types exported from `"@opentelemetry/api"` have been changed to be more specific.
-
-- `AttributeValue` renamed to `SpanAttributeValue`
-- `Attributes` renamed to `SpanAttributes`
-- `EntryTtl` renamed to `BaggageEntryTtl`
-- `EntryValue` renamed to `BaggageEntryValue`
-- `Status` renamed to `SpanStatus`
-- `StatusCode` renamed to `SpanStatusCode`
-
-### 0.15.0 to 0.16.0
-
-[PR-1863](https://github.com/open-telemetry/opentelemetry-js/pull/1863) removed public attributes `keepAlive` and `httpAgentOptions` from nodejs `CollectorTraceExporter` and `CollectorMetricExporter`
-
-### 0.14.0 to 0.15.0
-
-[PR-1764](https://github.com/open-telemetry/opentelemetry-js/pull/1764) removed some APIs from `Tracer`:
-
-- `Tracer.getCurrentSpan()`: use `api.getSpan(api.context.active())`
-- `Tracer.withSpan(span)`: use `api.context.with(api.setSpan(api.context.active(), span))`
-- `Tracer.bind(target)`: use `api.context.bind(target)`
-
-[PR-1797](https://github.com/open-telemetry/opentelemetry-js/pull/1797) chore!: split metrics into its own api package:
-
-- Any references to `require("@opentelemetry/api").metrics` will need to be changed to `require("@opentelemetry/api-metrics").metrics`
-
-[PR-1725](https://github.com/open-telemetry/opentelemetry-js/pull/1725) Use new gRPC default port
-
-- The default port used by `@opentelemetry/exporter-collector-grpc` is changed from `55680` to `4317`
-
-[PR-1749](https://github.com/open-telemetry/opentelemetry-js/pull/1749) chore: improve naming of span related context APIs
-
-- Rename `[gs]etActiveSpan()` to `[gs]etSpan()`
-- Rename `setExtractedSpanContext()` to `setSpanContext()`
-- Rename `getParentSpanContext()` to `getSpanContext()`
-
 ## Useful links
 
+- Upgrade guidelines: [Upgrade Guide](./doc/upgrade-guide.md)
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
 - For help or feedback on this project, join us in [GitHub Discussions][discussions-url]
 

diff --git a/maintenance/bug_triage.md → doc/contributing/bug_triage.md b/maintenance/bug_triage.md → doc/contributing/bug_triage.md
diff --git a/doc/GUIDELINES.md → doc/contributing/dependencies.md b/doc/GUIDELINES.md → doc/contributing/dependencies.md
@@ -1,14 +1,10 @@
-# OpenTelemetry JS Code Contribution Guide
-
-This document outlines the essential guidelines for contributing code to the OpenTelemetry JS repository. These guidelines are designed to ensure consistency, stability, and the highest quality of code across the project.
-
-## Dependencies
+# OpenTelemetry Dependencies
 
 This section refers to `"dependencies"` and `"devDependencies"` entries in `package.json` file.
 > [!IMPORTANT]
 > Not all libraries follow [Semantic Versioning](https://semver.org/). Even those who do might occasionally introduce breaking changes due to human errors. Exceptions to the guidelines in this document MAY be granted by Approvers or Maintainers to work around this.
 
-### Development Dependencies
+## Development Dependencies
 
 `"devDependencies"` SHOULD be pinned to reduce the risk of autobreaking the build. Since we cannot use the `package-lock.json` file (because the libraries are distributed without it), control over the version our contributors will get is limited. By using pinned versions, we prevent potential disruptions caused by unpinned versions.
 
@@ -17,15 +13,15 @@ This section refers to `"dependencies"` and `"devDependencies"` entries in `pack
 > [!NOTE]
 > As this approach might leave our project with outdated tooling, we adopt `renovate-bot`. This automated dependency update tool proactively opens pull requests upon the release of new patch/minor/major versions. The complete configuration for renovate-bot can be found in [renovate.json](../renovate.json) file.
 
-### @opentelemetry/* dependencies
+## @opentelemetry/* dependencies
 
 All packages from the `@opentelemetry/` namespace MUST have the same pinned version, as these dependencies are automatically updated on each release by lerna.
 
 **Example:** all packages under `packages/` should consistently maintain the same version, as should those under `experimental/packages/`.
 
 An exception is granted for dependencies on `@opentelemetry/api`, which, if used by the package SHOULD NOT be included as a `dependency`. `@opentelemetry/api` SHOULD be included as a `peerDependency` instead. The version range of the `peerDependency` SHOULD reflect the minimum supported, and SHOULD NOT allow versions greater than the latest released minor version.
 
-### Third-Party Library Dependencies
+## Third-Party Library Dependencies
 
 Packages categorized as third-party and listed under the `"dependencies"` section (e.g., @grpc/grpc-js, @grpc/proto-loader, shimmer, etc.) should remain unpinned and utilize the caret (`^`) symbol. This approach offers several advantages:
 

diff --git a/maintenance/npm_workspaces.md → doc/contributing/npm_workspaces.md b/maintenance/npm_workspaces.md → doc/contributing/npm_workspaces.md
diff --git a/maintenance/releasing.md → doc/contributing/releasing.md b/maintenance/releasing.md → doc/contributing/releasing.md