docs: add migration guides for all packages

There's a small maintenance overhead to adding these but I think they're
far more clear than a changelog for major breaking versions. We need to
include a lot of extra context and information and I think these guides
will reduce questions from other teams.

packages/app-info/README.md

@@ -14,6 +14,7 @@ A utility to get application information (e.g. the system code) in a consistent
     * [`appInfo.cloudProvider`](#appinfocloudprovider)
     * [`appInfo.herokuAppId`](#appinfoherokuappId)
     * [`appInfo.herokuDynoId`](#appinfoherokudynoId)
+  * [Migrating](#migrating)
   * [Contributing](#contributing)
   * [License](#license)
 
@@ -98,6 +99,12 @@ Get the `process.env.HEROKU_DYNO_ID` which is the dyno identifier
 
 This is derived from the dyno metadata
 
+
+## Migrating
+
+Consult the [Migration Guide](./docs/migration.md) if you're trying to migrate to a later major version of this package.
+
+
 ## Contributing
 
 See the [central contributing guide for Reliability Kit](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/docs/contributing.md).

packages/app-info/docs/migration.md

@@ -0,0 +1,28 @@
+
+# Migration guide for @dotcom-reliability-kit/app-info
+
+This document outlines how to migrate to the latest version of the Reliability Kit app-info package. Throughout this guide we use the following emoji and labels to indicate the level of change required:
+
+Emoji           | Label             | Meaning
+----------------|:------------------|:-------
+:red_circle:    | Breaking          | A breaking change which will likely require code or config changes to resolve
+:orange_circle: | Possibly Breaking | A breaking change that is unlikely to require code changes but things outside of the code (e.g. logs) may have changed
+
+* [Migrating from v1 to v2](#migrating-from-v1-to-v2)
+  * [Node.js 14 is no longer supported](#nodejs-14-is-no-longer-supported)
+* [Migrating from v2 to v3](#migrating-from-v2-to-v3)
+  * [Node.js 16 is no longer supported](#nodejs-16-is-no-longer-supported)
+
+
+## Migrating from v1 to v2
+
+### Node.js 14 is no longer supported
+
+**:red_circle: Breaking:** this version drops support for Node.js v14. If your app is already using Node.js v16 or above then you can migrate with no code changes.
+
+
+## Migrating from v2 to v3
+
+### Node.js 16 is no longer supported
+
+**:red_circle: Breaking:** this version drops support for Node.js v16. If your app is already using Node.js v18 or above then you can migrate with no code changes.

packages/crash-handler/README.md

@@ -10,6 +10,7 @@ A method to bind an uncaught exception handler to ensure that fatal application
     * [`options.process`](#optionsprocess)
 * [Compatibility](#compatibility)
   * [Migrating from Sentry](#migrating-from-sentry)
+* [Migrating](#migrating)
 * [Contributing](#contributing)
 * [License](#license)
 
@@ -83,6 +84,11 @@ registerCrashHandler({
 The Reliability Kit crash handler is a replacement for Sentry's uncaught exception handling, which your app is likely to be using. You'll need to migrate away from Sentry in order to use this module. [We maintain a migration guide for this on Confluence](https://financialtimes.atlassian.net/l/cp/eeTWSAxe).
 
 
+## Migrating
+
+Consult the [Migration Guide](./docs/migration.md) if you're trying to migrate to a later major version of this package.
+
+
 ## Contributing
 
 See the [central contributing guide for Reliability Kit](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/docs/contributing.md).

packages/crash-handler/docs/migration.md

@@ -0,0 +1,57 @@
+
+# Migration guide for @dotcom-reliability-kit/crash-handler
+
+This document outlines how to migrate to the latest version of the Reliability Kit crash-handler package. Throughout this guide we use the following emoji and labels to indicate the level of change required:
+
+Emoji           | Label             | Meaning
+----------------|:------------------|:-------
+:red_circle:    | Breaking          | A breaking change which will likely require code or config changes to resolve
+:orange_circle: | Possibly Breaking | A breaking change that is unlikely to require code changes but things outside of the code (e.g. logs) may have changed
+
+* [Migrating from v1 to v2](#migrating-from-v1-to-v2)
+  * [Node.js 14 is no longer supported](#nodejs-14-is-no-longer-supported)
+* [Migrating from v2 to v3](#migrating-from-v2-to-v3)
+  * [Switch to Reliability Kit logger](#switch-to-reliability-kit-logger)
+  * [Remove Sentry workarounds](#remove-sentry-workarounds)
+* [Migrating from v3 to v4](#migrating-from-v3-to-v4)
+  * [Node.js 16 is no longer supported](#nodejs-16-is-no-longer-supported)
+
+
+## Migrating from v1 to v2
+
+### Node.js 14 is no longer supported
+
+**:red_circle: Breaking:** this version drops support for Node.js v14. If your app is already using Node.js v16 or above then you can migrate with no code changes.
+
+
+## Migrating from v2 to v3
+
+### Switch to Reliability Kit logger
+
+**:orange_circle: Possibly Breaking:** this version switches to use [Reliability Kit's logger](https://github.com/Financial-Times/dotcom-reliability-kit/tree/main/packages/logger#readme) by default. This means that logs will not be sent directly to Splunk but will be sent to `stdout`. This may mean you lose some logs if you haven't configured your app to forward these logs somewhere more permanent.
+
+You may not need to change anything for this upgrade, for example, if your app uses Heroku log drains _or_ a Lambda log forwarder. [The logger migration guide has more information](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/packages/logger/docs/migration.md#n-logger-where-logs-get-sent).
+
+If you can't switch to Reliability Kit logger yet, then you can still use [n-logger](https://github.com/Financial-Times/n-logger) (the previous default logger) by manually passing it as an option when initialising Crash Handler:
+
+```js
+const registerCrashHandler = require('@dotcom-reliability-kit/crash-handler');
+const nLogger = require('@financial-times/n-logger').default;
+
+registerCrashHandler({
+    logger: nLogger
+});
+```
+
+### Remove Sentry workarounds
+
+**:orange_circle: Possibly Breaking:** this only impacts apps that use [n-express](https://github.com/Financial-Times/n-express) v27 or older. Previously, this module contained code to disable the default [Sentry](https://sentry.io/) error handling which was enabled by n-express.
+
+You can safely migrate to this version of Crash Handler if your app is either _not_ using n-express or is using n-express v28 or above.
+
+
+## Migrating from v3 to v4
+
+### Node.js 16 is no longer supported
+
+**:red_circle: Breaking:** this version drops support for Node.js v16. If your app is already using Node.js v18 or above then you can migrate with no code changes.

packages/errors/README.md

@@ -14,6 +14,7 @@ A suite of error classes which help you throw the most appropriate error in any
     * [`UpstreamServiceError`](#upstreamserviceerror)
     * [`UserInputError`](#userinputerror)
     * [`BaseError`](#baseerror)
+  * [Migrating](#migrating)
   * [Contributing](#contributing)
   * [License](#license)
 
@@ -220,6 +221,12 @@ throw new BaseError({
 });
 ```
 
+
+## Migrating
+
+Consult the [Migration Guide](./docs/migration.md) if you're trying to migrate to a later major version of this package.
+
+
 ## Contributing
 
 See the [central contributing guide for Reliability Kit](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/docs/contributing.md).

packages/errors/docs/migration.md

@@ -0,0 +1,28 @@
+
+# Migration guide for @dotcom-reliability-kit/errors
+
+This document outlines how to migrate to the latest version of the Reliability Kit errors package. Throughout this guide we use the following emoji and labels to indicate the level of change required:
+
+Emoji           | Label             | Meaning
+----------------|:------------------|:-------
+:red_circle:    | Breaking          | A breaking change which will likely require code or config changes to resolve
+:orange_circle: | Possibly Breaking | A breaking change that is unlikely to require code changes but things outside of the code (e.g. logs) may have changed
+
+* [Migrating from v1 to v2](#migrating-from-v1-to-v2)
+  * [Node.js 14 is no longer supported](#nodejs-14-is-no-longer-supported)
+* [Migrating from v2 to v3](#migrating-from-v2-to-v3)
+  * [Node.js 16 is no longer supported](#nodejs-16-is-no-longer-supported)
+
+
+## Migrating from v1 to v2
+
+### Node.js 14 is no longer supported
+
+**:red_circle: Breaking:** this version drops support for Node.js v14. If your app is already using Node.js v16 or above then you can migrate with no code changes.
+
+
+## Migrating from v2 to v3
+
+### Node.js 16 is no longer supported
+
+**:red_circle: Breaking:** this version drops support for Node.js v16. If your app is already using Node.js v18 or above then you can migrate with no code changes.

packages/eslint-config/README.md

@@ -4,6 +4,7 @@ A linting config, specifically focussed on enhancing code quality and proactivel
 
 - [Usage](#usage)
   - [Static Code Analysis](#static-code-analysis)
+- [Migrating](#migrating)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -35,6 +36,12 @@ Add the following command to the `scripts` object in your repository's package.j
 
 Run that command in your terminal to lint your files (either cd into the relevant directory or run from root). Any linting errors found by the config will be displayed in your terminal, with helpful suggestions on how to resolve them.
 
+
+## Migrating
+
+Consult the [Migration Guide](./docs/migration.md) if you're trying to migrate to a later major version of this package.
+
+
 ## Contributing
 
 See the [central contributing guide for Reliability Kit](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/docs/contributing.md).

packages/eslint-config/docs/migration.md

@@ -0,0 +1,36 @@
+
+# Migration guide for @dotcom-reliability-kit/eslint-config
+
+This document outlines how to migrate to the latest version of the Reliability Kit eslint-config package. Throughout this guide we use the following emoji and labels to indicate the level of change required:
+
+Emoji           | Label             | Meaning
+----------------|:------------------|:-------
+:red_circle:    | Breaking          | A breaking change which will likely require code or config changes to resolve
+:orange_circle: | Possibly Breaking | A breaking change that is unlikely to require code changes but things outside of the code (e.g. logs) may have changed
+
+* [Migrating from v1 to v2](#migrating-from-v1-to-v2)
+  * [Additional default ESLint rules added (v2)](#additional-default-eslint-rules-added-v2)
+* [Migrating from v2 to v3](#migrating-from-v2-to-v3)
+  * [Node.js 16 is no longer supported](#nodejs-16-is-no-longer-supported)
+
+
+## Migrating from v1 to v2
+
+### Additional default ESLint rules added (v2)
+
+**:orange_circle: Possibly Breaking:** this version adds a few new ESLint rules to the default configuration, the following rules now error:
+
+* [eqeqeq](https://eslint.org/docs/latest/rules/eqeqeq)
+* [no-extend-native](https://eslint.org/docs/latest/rules/no-extend-native)
+* [no-irregular-whitespace](https://eslint.org/docs/latest/rules/no-irregular-whitespace)
+* [no-undef](https://eslint.org/docs/latest/rules/no-undef)
+* [no-unused-vars](https://eslint.org/docs/latest/rules/no-unused-vars)
+
+You may need to make changes to your code if these linting errors are found.
+
+
+## Migrating from v2 to v3
+
+### Node.js 16 is no longer supported
+
+**:red_circle: Breaking:** this version drops support for Node.js v16. If your app is already using Node.js v18 or above then you can migrate with no code changes.

packages/log-error/README.md

@@ -12,6 +12,7 @@ A method to consistently log error object with optional request information. Thi
     * [`options.includeHeaders`](#optionsincludeheaders)
     * [`options.logger`](#optionslogger)
     * [`options.request`](#optionsrequest)
+* [Migrating](#migrating)
 * [Contributing](#contributing)
 * [License](#license)
 
@@ -259,6 +260,11 @@ When this option is defined, the logged data looks includes request data:
 ```
 
 
+## Migrating
+
+Consult the [Migration Guide](./docs/migration.md) if you're trying to migrate to a later major version of this package.
+
+
 ## Contributing
 
 See the [central contributing guide for Reliability Kit](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/docs/contributing.md).

packages/log-error/docs/migration.md

@@ -0,0 +1,56 @@
+
+# Migration guide for @dotcom-reliability-kit/log-error
+
+This document outlines how to migrate to the latest version of the Reliability Kit log-error package. Throughout this guide we use the following emoji and labels to indicate the level of change required:
+
+Emoji           | Label             | Meaning
+----------------|:------------------|:-------
+:red_circle:    | Breaking          | A breaking change which will likely require code or config changes to resolve
+:orange_circle: | Possibly Breaking | A breaking change that is unlikely to require code changes but things outside of the code (e.g. logs) may have changed
+
+* [Migrating from v1 to v2](#migrating-from-v1-to-v2)
+  * [Node.js 14 is no longer supported](#nodejs-14-is-no-longer-supported)
+* [Migrating from v2 to v3](#migrating-from-v2-to-v3)
+  * [Switch to Reliability Kit logger](#switch-to-reliability-kit-logger)
+  * [Unhandled errors now have a level of fatal](#unhandled-errors-now-have-a-level-of-fatal)
+* [Migrating from v3 to v4](#migrating-from-v3-to-v4)
+  * [Node.js 16 is no longer supported](#nodejs-16-is-no-longer-supported)
+
+
+## Migrating from v1 to v2
+
+### Node.js 14 is no longer supported
+
+**:red_circle: Breaking:** this version drops support for Node.js v14. If your app is already using Node.js v16 or above then you can migrate with no code changes.
+
+
+## Migrating from v2 to v3
+
+### Switch to Reliability Kit logger
+
+**:orange_circle: Possibly Breaking:** this version switches to use [Reliability Kit's logger](https://github.com/Financial-Times/dotcom-reliability-kit/tree/main/packages/logger#readme) by default. This means that logs will not be sent directly to Splunk but will be sent to `stdout`. This may mean you lose some logs if you haven't configured your app to forward these logs somewhere more permanent.
+
+You may not need to change anything for this upgrade, for example, if your app uses Heroku log drains _or_ a Lambda log forwarder. [The logger migration guide has more information](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/packages/logger/docs/migration.md#n-logger-where-logs-get-sent).
+
+If you can't switch to Reliability Kit logger yet, then you can still use [n-logger](https://github.com/Financial-Times/n-logger) (the previous default logger) by manually passing it as an option when logging errors:
+
+```js
+const { logHandledError } = require('@dotcom-reliability-kit/log-error');
+const nLogger = require('@financial-times/n-logger').default;
+
+logHandledError({
+    error: new Error('Something went wrong'),
+    logger: nLogger
+});
+```
+
+### Unhandled errors now have a level of fatal
+
+**:orange_circle: Possibly Breaking:** errors logged with `logUnhandledError` will now have a `level` property of `fatal` rather than `error`. This shouldn't require code changes but you may need to update your saved Splunk searches or dashboards.
+
+
+## Migrating from v3 to v4
+
+### Node.js 16 is no longer supported
+
+**:red_circle: Breaking:** this version drops support for Node.js v16. If your app is already using Node.js v18 or above then you can migrate with no code changes.

packages/logger/README.md

@@ -32,9 +32,7 @@ A simple and fast logger based on [Pino](https://getpino.io/), with FT preferenc
     * [Production usage](#production-usage)
     * [Testing](#testing)
     * [Compatibility](#compatibility)
-      * [Migrating from n-logger](./docs/migration.md#migrating-from-n-logger)
-      * [Migrating from n-mask-logger](./docs/migration.md#migrating-from-n-mask-logger)
-      * [Migrating from n-serverless-logger](./docs/migration.md#migrating-from-n-serverless-logger)
+  * [Migrating](#migrating)
   * [Contributing](#contributing)
   * [License](#license)
 
@@ -615,6 +613,11 @@ jest.mock('@dotcom-reliability-kit/logger', () => ({
 `@dotcom-reliability-kit/logger` is compatible with most use cases of [n-logger](https://github.com/Financial-Times/n-logger), [n-mask-logger](https://github.com/Financial-Times/n-mask-logger), and [n-serverless-logger](https://github.com/Financial-Times/n-serverless-logger). We tried hard to make migration as easy as possible from these libraries. The full list of differences are available in the [Migration Guide](./docs/migration.md) as well as tips on migrating.
 
 
+## Migrating
+
+Consult the [Migration Guide](./docs/migration.md) if you're trying to migrate to a later major version of this package.
+
+
 ## Contributing
 
 See the [central contributing guide for Reliability Kit](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/docs/contributing.md).

packages/logger/docs/migration.md

@@ -5,12 +5,10 @@ This document outlines how to migrate to the latest version of the Reliability K
 
 Emoji           | Label             | Meaning
 ----------------|:------------------|:-------
-:red_circle:    | Breaking          | A breaking change which will definitely require code changes to resolve
-:orange_circle: | Possibly Breaking | A breaking change to the output of the library which may require extra steps
+:red_circle:    | Breaking          | A breaking change which will likely require code or config changes to resolve
+:orange_circle: | Possibly Breaking | A breaking change that is unlikely to require code changes but things outside of the code (e.g. logs) may have changed
 :yellow_circle: | Deprecation       | A deprecated feature which will require code changes in the future
 
-## Table of contents
-
   * [Migrating from n-logger](#migrating-from-n-logger)
     * [Where logs get sent](#n-logger-where-logs-get-sent)
     * [Error serialization changes](#n-logger-error-serialization-changes)
@@ -31,6 +29,11 @@ Emoji           | Label             | Meaning
     * [Logger property changes](#n-serverless-logger-property-changes)
     * [Logger method changes](#n-serverless-logger-method-changes)
     * [Environment variable changes](#n-serverless-logger-environment-variable-changes)
+  * [Migrating from v1 to v2](#migrating-from-v1-to-v2)
+    * [Node.js 14 is no longer supported](#nodejs-14-is-no-longer-supported)
+  * [Migrating from v2 to v3](#migrating-from-v2-to-v3)
+    * [Node.js 16 is no longer supported](#nodejs-16-is-no-longer-supported)
+
 
 ## Migrating from n-logger
 
@@ -265,3 +268,27 @@ logger.info('Hello');
 The following environment variables have been deprecated.
 
   * **`SPLUNK_LOG_LEVEL`:** This environment variable will be used if a `LOG_LEVEL` environment variable is not present, however it may be removed in a later version of the Reliability Kit logger. It's best to migrate to `LOG_LEVEL` early.
+
+
+## Migrating from v1 to v2
+
+### Node.js 14 is no longer supported
+
+**:red_circle: Breaking:** this version drops support for Node.js v14. If your app is already using Node.js v16 or above then you can migrate with no code changes.
+
+
+## Migrating from v2 to v3
+
+### Node.js 16 is no longer supported
+
+**:red_circle: Breaking:** this version drops support for Node.js v16. If your app is already using Node.js v18 or above then you can migrate with no code changes.
+
+### Log times are now ISO 8601 timestamps
+
+**:orange_circle: Possibly Breaking:** The `time` property of all logs is now an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) representation of the time that the log was sent rather than a timestamp. There are two ways this could be a breaking change in your app:
+
+  1. If you have saved searches or dashboards that rely on the `time` property being a number.
+
+  2. If you're using the `withTimestamps` or `useIsoTimeFormat` options with TypeScript, because these options have now been removed from the code and the type definitions.
+
+If neither of the above is true, this should be a safe update with no code changes.