Add migration guide for Uppy 3.x, Companion 4.x, and Robodog

website/src/docs/migration-guides.md

@@ -8,7 +8,118 @@ category: "Docs"
 
 These cover all the major Uppy versions and how to migrate to them.
 
-## Migrate to 2.0.0
+## Migrate from Uppy 2.x to 3.x
+
+### Uppy is pure ESM
+
+Following the footsteps of many packages, we now only ship Uppy core and its plugins as
+[ECMAScript Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) (ESM).
+On Uppy 2.x, we were shipping CommonJS.
+
+If are already using ESM yourself, or are using the CDN builds, nothing changes for you!
+
+If you are using CommonJS, you might need to add some tooling for everything to work, or you might
+want to refactor your codebase to ESM – refer to
+the [Pure ESM package](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c)
+gist for added information and help on how to do that.
+
+### Robodog is deprecated
+
+Uppy is flexible and extensible through plugins. But the integration code could sometimes be daunting. This is what brought [Robodog](/docs/robodog/) to life. An alternative with the same features, but with a more ergonomic and minimal API.
+
+But, it didn’t come with its own set of new problems:
+
+* It tries to do the exact same, but it looks like a different product
+* It’s confusing for users whether they want to use Robodog or Uppy directly.
+* Robodog is more ergonomic because it’s limited. When you hit such a limit, you need to refactor everything to Uppy with plugins.
+* Documentation is scarce, and the trade offs are unclear
+* It’s not marketed, you need to stumble on it in the docs.
+* Extra maintenance burden
+* Extra hosting effort and costs
+
+This has now led us to deprecating Robodog and embrace Uppy for its strong suits; modularity and flexibility. At the same time, we also introduced something to take away some repetitive integration code: [`@uppy/remote-sources`](/docs/remote-sources).
+
+To migrate from Robodog to Uppy plugins, go through the [list of plugins](/docs/plugins/) and install and use the ones you need.
+
+### Smaller breaking changes
+
+We also made a couple of changes which are technically breaking, but unlikely to be so for most users (making something internal private, for instance).
+
+#### `@uppy/core`
+
+* Remove `AggregateError` polyfill.
+  * reason: it’s supported by most modern browsers and [can be polyfilled by the user](https://github.com/transloadit/uppy/pull/3532#discussion_r818602636) if needed.
+  * migrate: install a `AggregateError` polyfill or use `core-js`.
+* Remove `reset()` method.
+  * reason: it’s a duplicate of `cancelAll`, but with a less intention revealing name.
+  * migrate: use `cancelAll`.
+* Remove backwards compatible exports (static properties on `Uppy`). Exports, such as `debugLogger`, used to also be accesible on the `Uppy` export. This has now been removed.
+  * reason: transition to ESM.
+  * migrate: import the `Uppy` class by default and/or use named exports for everything else.
+
+#### `@uppy/aws-s3-multipart`
+
+* Remove `client` getter and setter.
+  * reason: internal usage only.
+  * migrate: use exposed options only.
+
+#### `@uppy/react`
+
+* Don’t expose `validProps` on the exported components.
+  * reason: internal usage only.
+  * migrate: use exposed options only.
+
+#### `@uppy/store-redux`
+
+* Remove backwards compatible exports (static properties on `ReduxStore`). Exports, such as `reducer`, used to also be accesible on the `ReduxStore` export. This has now been removed.
+  * reason: transition to ESM.
+  * migrate: use named imports.
+
+#### `@uppy/thumbnail-generator`
+
+* Remove `rotateImage`, `protect`, and `canvasToBlob` from plugin prototype.
+  * reason: internal usage only.
+  * migrate: use exposed options only.
+
+## Migrate from Companion 3.x to 4.x
+
+### Minimum required Node.js version is v14.20.0
+
+Aligning with the Node.js [Long Term Support (LTS) schedule](https://nodejs.org/en/about/releases/) and to use modern syntax features.
+
+### `companion.app()` returns `{ app, emitter }` instead of `app`
+
+Companion 3.x provides the emitter as `companionEmitter` on `app`. As of 4.x, an object is returned
+with an `app` property (express middleware) and an `emitter` property (event emitter). This
+provides more flexibility in the future and follows best practices.
+
+### Removed compatibility for legacy Custom Provider implementations
+
+[Custom Provider](https://uppy.io/docs/companion/#Adding-custom-providers)
+implementations must use the Promise API. The callback API is no longer supported.
+
+### Default to no ACL for AWS S3
+
+Default to no [ACL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html) for S3 uploads. Before the default was `public-read` but AWS now discourages ACLs. The environment variable `COMPANION_AWS_DISABLE_ACL` is also removed, instead Companion only uses `COMPANION_AWS_ACL`.
+
+### `protocol` sent from Uppy in any `get` request is now required (before it would default to Multipart).
+
+If you use any official Uppy plugins, then no migration is needed. For custom plugins that talk to Companion, make to send along the `protocol` header with a value of `multipart`, `s3Multipart`, or `tus`.
+
+### `emitSuccess` and `emitError` are now private methods on the `Uploader` class.
+
+It’s unlikely you’re using this, but it’s technically a breaking change.
+In general, don’t depend on implicitly internal methods, use exposed APIs instead.
+
+### Removed `chunkSize` backwards compatibility for AWS S3 Multipart
+
+`chunkSize` option will now be used as `partSize` in AWS multipart. Before only valid values would be respected. Invalid values would be ignored. Now any value will be passed on to the AWS SDK, possibly throwing an error on invalid values.
+
+### Removed backwards compatibility for `/metrics` endpoint
+
+TODO @mifi
+
+## Migrate from Uppy 1.x to 2.x
 
 ### New bundle requires manual polyfilling
 
@@ -247,7 +358,7 @@ Uppy 1.0 will continue to receive bug fixes for three more months (until <time d
 
 We hope you’ll waste no time in taking Uppy 2.0 out for a walk. When you do, please let us know what you thought of it on [Reddit](https://www.reddit.com/r/javascript/comments/penbr7/uppy_file_uploader_20_smaller_and_faster_modular/), [HN](https://news.ycombinator.com/item?id=28359287), ProductHunt, or [Twitter](https://twitter.com/uppy_io/status/1432399270846603264). We’re howling at the moon to hear from you!
 
-## Migrating Companion v1 to v2
+## Migrate from Companion 1.x to 2.x
 
 ### Prerequisite