Add an upgrade guide for v2

docs/introduction/upgrade-to-v2.md

@@ -0,0 +1,142 @@
+---
+title: Upgrade to fp-ts 2.x
+parent: Introduction
+nav_order: 5
+has_toc: false
+---
+
+# Upgrade to version 2.x
+
+`[email protected]` brings with it some major improvements, but also breaking changes and the removal of deprecated APIs. This document will help you understand what changed and how you can upgrade your existing codebase.
+{: .fs-6 .fw-300 }
+
+---
+
+The major changes in `[email protected]` are:
+
+- Requires TypeScript 3.5+
+- `[email protected]` has been released with backported 2.x features for a gradual upgrade path
+- Data types are no longer implemented as classes, resulting in a new API using `pipe`
+- The `run()` method on `IO`, `Task`, etc. has been replaced with a thunk
+- Deprecations
+  - `HKT`: Replaced `Type<n>` with `Kind<n>`
+  - Replaced `Setoid` with `Eq`
+  - Several modules were removed, e.g. `Exception`, `Free`, `StrMap`, `Trace`, `Validation`, …
+  - Read the [full changelog](https://github.com/gcanti/fp-ts/pull/881) for all the changes
+
+## Upgrading from version 1.x
+
+You can gradually upgrade your existing codebase using the `[email protected]` release; the new `[email protected]` APIs have been backported to this release.
+
+1. Upgrade TypeScript to version 3.5+
+1. Install `[email protected]`, which contains the new `[email protected]` APIs
+1. Optional: activate the `@obsolete` rule for `tslint` to get guidance on what to change
+1. Familiarise yourself with [the new API](https://github.com/gcanti/fp-ts/pull/881)
+1. Gradually replace the existing code with the new API
+1. Upgrade to `[email protected]` and make sure to also upgrade all dependencies that rely on `fp-ts`
+
+### tslint rule
+
+In order to make easier to spot all the occurrences of chainable APIs without depending on `@deprecated`, which would force you to migrate in one shot, a custom tslint rule is provided (`@obsolete`).
+
+Add the following lines to your `tslint.json` to turn the `@obsolete` rule on:
+
+```diff
+{
++  "rulesDirectory": ["./node_modules/fp-ts/rules"],
+   "rules": {
++    "obsolete": true
+   }
+}
+```
+
+### Dependencies
+
+Make sure to always have a single version of `fp-ts` installed in your project. Multiple versions are known to cause `tsc` to hang during compilation. You can check the versions currently installed using `npm ls fp-ts`: make sure there's a single version and all the others are marked as `deduped`.
+
+## The new API
+
+In `[email protected]` data types are no longer implemented with classes; the biggest change resulting from this is that the chainable API has been removed. As an alternative, a `pipe` function is provided, along with suitable data-last top level functions (one for each deprecated method). This is best shown with an example:
+
+v1 (deprecated)
+{: .label .label-red .mt-5 }
+
+```ts
+import * as O from 'fp-ts/lib/Option'
+
+O.some(1)
+  .map(n => n * 2)
+  .chain(n === 0 ? O.none : O.some(1 / n))
+  .filter(n => n > 1)
+  .foldL(() => 'ko', () => 'ok')
+```
+
+v2 (new)
+{: .label .label-green .mt-5 }
+
+```ts
+import * as O from 'fp-ts/lib/Option'
+import { pipe } from 'fp-ts/lib/pipeable'
+
+pipe(
+  O.some(1),
+  O.map(n => n * 2),
+  O.chain(n === 0 ? O.none : O.some(1 / n)),
+  O.filter(n => n > 1),
+  O.fold(() => 'ko', () => 'ok')
+)
+```
+
+If you are interested, read about the [benefits of the new API](https://github.com/gcanti/fp-ts/issues/823#issuecomment-486066792) in the technical discussion leading to `[email protected]`.
+
+### Replacement of the `run()` method
+
+The `run()` method on `IO`, `Task`, etc. has been replaced with a thunk:
+
+v1 (deprecated)
+{: .label .label-red .mt-5 }
+
+```ts
+import { Task } from 'fp-ts/lib/Task'
+
+const deepThought = new Task<number>(() => Promise.resolve(42))
+
+deepThought.run().then(n => {
+  console.log(`The answer is ${n}.`)
+})
+```
+
+v2 (new)
+{: .label .label-green .mt-5 }
+
+```ts
+import { Task } from 'fp-ts/lib/Task'
+
+const deepThought: Task<number> = () => Promise.resolve(42)
+
+deepThought().then(n => {
+  console.log(`The answer is ${n}.`)
+})
+```
+
+### Removed modules
+
+- `Exception`
+- `Free`
+- `FreeGroup`
+- `IxIO`
+- `IxMonad`
+- `Monoidal`
+- `Pair`
+- `StrMap` (use [Record](../modules/Record.ts) instead)
+- `Trace`
+- `Validation` (use [Either](../modules/Either.ts)'s `getValidation`)
+- `Zipper`
+
+## References
+
+If you're interested in reading up on how this release came to be, have a look at the following discussions:
+
+- The technical [discussion leading to v2](https://github.com/gcanti/fp-ts/issues/823)
+- [Version 1.19 (backport)](https://github.com/gcanti/fp-ts/pull/881)
+- [The 2.0.0 release](https://github.com/gcanti/fp-ts/commit/7bda18e34eed996a08afdd6a0a61025087f99593)