Add migration guide

MIGRATING.md

@@ -0,0 +1,27 @@
+# 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 subpath exports](https://nodejs.org/api/packages.html#packages_package_entry_points) 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. If you're using TypeScript, your [`moduleResolution`](https://www.typescriptlang.org/tsconfig#moduleResolution) must be set to `"node16"`, `"nodenext"` or `"bundler"`.
+
+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/master/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

@@ -28,6 +28,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.
 These type definitions require TypeScript version 4.7 or higher.
 
+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 -->
@@ -104,6 +107,7 @@ Thanks to these people for their work on [the original polyfill][creatorrr-polyf
 [spec]: https://streams.spec.whatwg.org
 [ref-impl]: https://github.com/whatwg/streams
 [ponyfill]: https://github.com/sindresorhus/ponyfill
+[migrating]: https://github.com/MattiasBuelens/web-streams-polyfill/blob/v4/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