Add migration guide

MIGRATING.md

@@ -0,0 +1,40 @@
+# Migrating
+
+## Version 3 to 4
+
+Version 4 restructures the library's exports to have more modern defaults, and employs modern best practices for
+publishing npm packages.
+
+* The default export (i.e. `import "web-streams-polyfill"`) is now the *ponyfill* variant instead of the *polyfill*
+  variant, to avoid modifying the global scope. If you do want to install the polyfill on the global scope, switch to
+  the `polyfill` variant.
+* The default export uses ES2015 syntax and targets modern Node and browser environments. If you need to support ES5
+  environments, switch to either the `es5` or `polyfill/es5` variant.
+* The polyfill variant no longer re-exports the ponyfill,
+  so `import { ReadableStream } from "web-streams-polyfill/polyfill"` won't work. Instead, use the
+  global `ReadableStream` variable directly after loading the polyfill, or switch to the default (non-polyfill) variant.
+* The project
+  uses [Node's package entry points](https://nodejs.org/api/packages.html#packages_package_entry_points) (`exports`
+  in `package.json`) to provide each variant as
+  a [dual module (UMD/ESM)](https://nodejs.org/api/packages.html#packages_dual_commonjs_es_module_packages). You need
+  Node 12.20.0 or higher to resolve these variants. If you're using a bundler (like webpack or Rollup), you need to make
+  sure it's up-to-date too.
+
+Version 4 also focuses on reducing the download size of the published npm package.
+
+* All published JavaScript code is now minified, without source maps. If you need to debug the polyfill, you
+  can [clone it](https://github.com/MattiasBuelens/web-streams-polyfill)
+  and [build it yourself](https://github.com/MattiasBuelens/web-streams-polyfill/blob/v3.1.0/CONTRIBUTING.md).
+* The ES2018 variant was removed, since it had only minor differences with the ES2015 variant. If you were using this
+  variant, switch to the default export instead.
+
+The following table shows how to upgrade your V3 import to their equivalent V4 import:
+
+| v3 import | v4 import | description |
+| --- | --- | --- |
+| `web-streams-polyfill` | `web-streams-polyfill/polyfill/es5` | ES5+ polyfill |
+| `web-streams-polyfill/es6` | `web-streams-polyfill/polyfill` | ES2015+ polyfill |
+| `web-streams-polyfill/es2018` | `web-streams-polyfill/polyfill` | ES2015+ polyfill |
+| `web-streams-polyfill/ponyfill` | `web-streams-polyfill/es5` | ES5+ ponyfill |
+| `web-streams-polyfill/ponyfill/es6` | `web-streams-polyfill` | ES2015+ ponyfill |
+| `web-streams-polyfill/ponyfill/es2018` | `web-streams-polyfill` | ES2015+ ponyfill |

README.md

@@ -32,6 +32,9 @@ This library comes in multiple variants:
 
 Each variant also includes TypeScript type definitions, compatible with the DOM type definitions for streams included in TypeScript.
 
+In version 4, the list of variants was reworked to have more modern defaults and to reduce the download size of the package.
+See the [migration guide][migrating] for more information.
+
 Usage as a polyfill:
 ```html
 <!-- option 1: hosted by unpkg CDN -->
@@ -105,6 +108,7 @@ Thanks to these people for their work on [the original polyfill][creatorrr-polyf
 [ref-impl]: https://github.com/whatwg/streams
 [ponyfill]: https://github.com/sindresorhus/ponyfill
 [amd]: https://requirejs.org/docs/whyamd.html
+[migrating]: https://github.com/MattiasBuelens/web-streams-polyfill/blob/next/MIGRATING.md
 [promise-support]: https://kangax.github.io/compat-table/es6/#test-Promise
 [promise-polyfill]: https://www.npmjs.com/package/promise-polyfill
 [rs-asynciterator]: https://streams.spec.whatwg.org/#rs-asynciterator