add migration guide for 3.x to 4.x (#3137)

* add migration guide for 3.x to 4.x

* Update MIGRATING.md

Co-authored-by: Juan Antonio Fernández de Alba <[email protected]>

* Update MIGRATING.md

Co-authored-by: Juan Antonio Fernández de Alba <[email protected]>

* Update README.md

Co-authored-by: Ugaitz Urien <[email protected]>

---------

Co-authored-by: Juan Antonio Fernández de Alba <[email protected]>
Co-authored-by: Ugaitz Urien <[email protected]>

Author: 3 people

MIGRATING.md

@@ -4,6 +4,164 @@ This guide describes the steps to upgrade dd-trace from a major version to the
 next. If you are having any issues related to migrating, please feel free to
 open an issue or contact our [support](https://www.datadoghq.com/support/) team.
 
+## 3.0 to 4.0
+
+### Node 14 is no longer supported
+
+Node.js 14 has reached EOL in April 2023 and is no longer supported. Generally
+speaking, we highly recommend always keeping Node.js up to date regardless of
+our support policy.
+
+### The `orphanable` option was removed
+
+This option was only useful internally for a single integration that has since
+been removed. It was never useful for manual instrumentation since all that is
+needed to orphan a span on creation is to use
+`tracer.trace('web.request', { childOf: null })`.
+
+### Support for `jest-jasmine2` has been removed
+
+The default test runner for Jest was changed to `jest-circus` around 2 years ago and
+is no longer supported by our Jest integration for CI Visibility. We recommend
+switching to `jest-circus` to anyone still using `jest-jasmine2`.
+
+### Support for older Next.js versions was removed
+
+We now support only Next.js 10.2 and up.
+
+### W3C headers are now prioritized over Datadog headers
+
+As we move towards open standards, we have decided to prioritize W3C Trace
+Context headers over our own vendor-specific headers for context propagation
+across services. For most applications this shouldn't change anything and
+distributed tracing should continue to work seamlessly.
+
+In some rare cases it's possible that some of the services involved in a trace
+are not instrumented by Datadog at all which can cause spans within the trace to
+become disconnected. While the data would still be available in the UI, the
+relationship between spans would no longer be visible. This can be addressed by
+restoring the previous behaviour using
+`DD_TRACE_PROPAGATION_STYLE='datadog,tracecontext'`.
+
+## 2.0 to 3.0
+
+### Node 12 is no longer supported
+
+Node.js 12 has been EOL since April 2022 and is no longer supported. Generally
+speaking, we highly recommend always keeping Node.js up to date regardless of our
+support policy.
+
+### HTTP query string reported by default
+
+HTTP query strings are now reported by default as part of the `http.url` tag.
+This change is considered breaking only because there might be sensitive data
+in the query string. A default regular expression based obfuscator is provided
+for common use cases like API keys, but if your use case is not covered, the
+[DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP](https://datadoghq.dev/dd-trace-js/#tracer-settings)
+environment variable can be used to control what is obfuscated, and a value of
+`.*` would redact the query string entirely.
+
+### HTTP operation name change
+
+The HTTP integration now uses `web.request` for incoming requests and continues
+to use `http.request` for outgoing requests. When using a supported web
+framework like Express, this change will have no effect because the root span
+would already have an operation name override like `express.request`.
+Any [monitor](https://docs.datadoghq.com/monitors/create/types/apm/?tab=apmmetrics)
+on `http.request` for incoming requests should be updated to `web.request`.
+
+With this change, both operation names also appear under the main service name
+and are no longer split between the server service name and a separate client
+service name suffixed with `-http-client`.
+
+### gRPC operation name change
+
+The gRPC integration now uses `grpc.server` for incoming requests and
+`grpc.client` for outgoing requests. Any
+[monitor](https://docs.datadoghq.com/monitors/create/types/apm/?tab=apmmetrics)
+on `grpc.request` should be updated to one of these.
+
+With this change, both operation names also appear under the main service name
+and are no longer split between the server service name and a separate client
+service name suffixed with `-http-client`.
+
+### Removal of `fs` integration
+
+The `fs` integration was removed as it was originally added without an actual
+use case, and it's been problematic ever since. It's noisy, the output is
+confusing when using streams, errors that are handled higher in the stack end up
+being captured, etc.
+
+If you had any use for file system instrumentation, please let us know so we can
+provide an alternative.
+
+### Scope binding for promises and event emitters
+
+It's no longer possible to bind promises using `tracer.scope().bind(promise)` or
+event emitters using `tracer.scope().bind(emitter)`. These were historically
+added mostly for internal use, and changes to context propagation over the years
+made them unnecessary, both internally and externaly. If one of these is used
+anywhere, the call will simply be ignored and no binding will occur.
+
+To bind the `then` handler of a promise, bind the function directly directly:
+
+```js
+promise.then(tracer.scope().bind(handler))
+```
+
+To bind all listeners for an event, wrap the call to `emit` directly instead:
+
+```js
+tracer.scope().activate(span, () => {
+  emitter.emit('event')
+})
+```
+
+To bind individual listeners, bind the listener function directly instead:
+
+```js
+emitter.on('event', tracer.scope().bind(listener, span))
+```
+
+### Removed APIs
+
+The following APIs have been deprecated for a long time and have now been
+completely removed:
+
+- `tracer.currentSpan()`
+- `tracer.bindEmitter()`
+
+Since these have not been recommended nor publicly documented for years at this
+point, there should be no impact as no application is expected to be using them.
+
+### CI Visibility new entrypoints
+
+#### Cypress
+
+`dd-trace/cypress/plugin` and `dd-trace/cypress/support` are removed, so you won't 
+be able to use them for your `cypress` instrumentation. Use `dd-trace/ci/cypress/plugin`
+and `dd-trace/ci/cypress/support` instead for your plugin and support configuration 
+respectively. 
+
+#### Jest
+
+The use of `'dd-trace/ci/jest/env'` in [`testEnvironment`](https://jestjs.io/docs/configuration#testenvironment-string)
+is no longer supported. 
+To instrument `jest` tests now, add `'-r dd-trace/ci/init'` to the `NODE_OPTIONS` environment
+variable passed to the process running the tests, for example, `NODE_OPTIONS='-r dd-trace/ci/init' yarn test`.
+
+#### Mocha
+
+The use of `--require dd-trace/ci/init` as a `mocha` flag is no longer supported. 
+To instrument `mocha` tests now, add `'-r dd-trace/ci/init'` to the `NODE_OPTIONS` environment
+variable passed to the process running the tests, for example, `NODE_OPTIONS='-r dd-trace/ci/init' yarn test`.
+
+#### Cucumber
+
+The use of `--require-module dd-trace/ci/init` as a `cucumber-js` flag is no longer supported.
+To instrument `cucumber-js` tests now, add `'-r dd-trace/ci/init'` to the `NODE_OPTIONS` environment
+variable passed to the process running the tests, for example, `NODE_OPTIONS='-r dd-trace/ci/init' yarn test`.
+
 ## 1.0 to 2.0
 
 ### Configuration

README.md

@@ -153,6 +153,11 @@ $ yarn lint
 
 ### Experimental ESM Support
 
+> **Warning**
+> 
+> ESM support has been temporarily disabled starting from Node 20 as significant
+> changes are in progress.
+
 ESM support is currently in the experimental stages, while CJS has been supported
 since inception. This means that code loaded using `require()` should work fine
 but code loaded using `import` might not always work.