diff --git a/docs/migration-guides/v2/migration-guide.md b/docs/migration-guides/v2/migration-guide.md
new file mode 100644
index 0000000000..ccdf961b1d
--- /dev/null
+++ b/docs/migration-guides/v2/migration-guide.md
@@ -0,0 +1,132 @@
+Looking at https://github.com/ably/ably-js/compare/64caf8e52152a1ed7b0c1ca32689e2e45369dca8...2462e9bfa412284a3c3975ad83a8ea4da9d9e7f4 (the same commit range used for commit `dd8db94` of changelog)
+
+OK, here’s the migration guide (I think there could be two documents):
+
+## Migration guide for ably-js
+
+Start with a general statement about first being on the latest version of 1.x and addressing all deprecation warnings.
+
+### Making use of new features
+
+#### Using the modular variant of the library
+
+- [Distribute an ECMAScript module variant of the library](https://github.com/ably/ably-js/commit/21fcf137f585591dfcbc1937caacf1ad76af57ee) (and the modular variant in general, with less logging, tree-shakability etc)
+
+TODO again, not clear to me, thinking about it now, why we decided to ship the modular variant in v2; presumably we could do this in v1. Is it a business decision? I guess it also wouldn’t be clear what to do about crypto; CryptoJS isn’t tree-shakable so we’d either have to take the size hit in modular variant, or exclude crypto from modular variant. Furthermore, we wouldn’t necessarily be able to make use of the `exports` key in `package.json`.
+
+#### `Crypto.generateRandomKey()` now works with promises
+
+- [Change Crypto.generateRandomKey API to use Promises](https://github.com/ably/ably-js/commit/a0105eb80ef6a9c133b4fc861cd2fc0aea71afc5)  — it’s actually that it now _supports_ promises. Not sure why I put this into v2, though; the support could have gone in v1. TODO I think this would be good to put in v1
+
+### Being aware of unsupported platforms
+
+- removal of a bunch of supporting code for older browsers (I think the documentation that states the new platform compatibility is not in this commit range)
+- JSONP support removed ("for browsers that do not support cross-origin XHR")
+
+### Being aware of crypto restrictions
+
+- [Use Web Crypto for encrypting and decrypting on web](https://github.com/ably/ably-js/commit/fcdb9f35ebeaf47883493be04d2ff3d0f985a4fc) (means that encryption is only available in a secure context)
+
+### Migrating existing code to handle breaking changes
+
+#### All users
+
+##### Removal of callbacks API and APIs supporting dual functioning
+
+Affecting everyone:
+
+- [Remove the callbacks public API](https://github.com/ably/ably-js/commit/2a2ed49e40e6ce9a8b1a119b66b2f3eeaf235054)
+- [Remove the `Promise` static property](https://github.com/ably/ably-js/commit/693804c5499691766de7b6580d39ffbe87887676)
+- [Remove `promises.js` / `.d.ts`](https://github.com/ably/ably-js/commit/6cf248fbc18434629def4fa7a37b006a396afd76)
+
+Affecting only TypeScript users:
+
+- [Merge `*Base` and `*Promise` classes](https://github.com/ably/ably-js/commit/6cb717990d5a993ebd6e0430b2b2629660c27cf8)
+
+##### Removal of CryptoJS library
+
+This will be about code changes (e.g. being able to interact with `WordArray`, as opposed to the above "being aware of crypto restrictions" which is about making sure you only use secure context for crypto)
+
+- [Remove all usage of the CryptoJS library](https://github.com/ably/ably-js/commit/f1bf7480ec2b758a8bce443d07b4415fe167707f) (I guess interesting in the context of reduced dependencies — anything else along these lines to mention?)
+- was CryptoJS mentioned anywhere in public API? e.g. being able to pass a `WordArray`
+- [Make CipherParams.key an ArrayBuffer on web instead of a WordArray](https://github.com/ably/ably-js/commit/e14f1bf7b8996c74f91f5c0486a1d734b0c4cbe6)
+
+##### Removal of `noencryption` variant of the library
+
+- [Remove the `noencryption` variant of the library](https://github.com/ably/ably-js/commit/dc47992bc6697adb80d3e638ce20495975813f31)
+
+#### Removal of web workers variant of the library
+
+- [Makes modular variant of the library available to Web Workers](https://github.com/ably/ably-js/commit/ae0ea991eb4c54655be72c991430c88ec2a61672) (and removes the `ably/build/webworker*` file)
+
+#### Removal of `ably-commonjs*.js` files
+
+- [removed `ably-commonjs*.js` files](https://github.com/ably/ably-js/commit/359f9a79ac1b31bc544b2b04bed206c439dea541)
+
+(this affects the guidance in the `README` about directly referencing this file — and I’m not even sure if that guidance is valid post `exports`, need to check)
+
+#### `Rest.request` mandatory version parameter
+
+- [Add mandatory version param to Rest.request](https://github.com/ably/ably-js/commit/ba77bfb0d2b59210aec1f920604b2f81096f870c)
+
+TODO could we implement this in v1 and add a deprecation? I guess we *could*, do we want to?
+
+#### `fromEncoded*` methods are now async
+
+- [Make Message#fromEncoded/fromEncodedArray async](https://github.com/ably/ably-js/commit/c19b68893df6fe01521b0b025a654108136b0d24)
+- [Make PresenceMessage#fromEncoded/fromEncodedArray async](https://github.com/ably/ably-js/commit/0ba216429905ef870b296db702196dc0d2d08091)
+
+#### Removal of client options
+
+##### Already deprecated
+
+- [Remove DeprecatedClientOptions.host](https://github.com/ably/ably-js/commit/5330f75feb3c01aff64faa7c66dbfca10c03c924)
+- [Remove DeprecatedClientOptions.wsHost](https://github.com/ably/ably-js/commit/616d2f24ec4281f87379d16702cff5119082850b)
+- [Remove DeprecatedClientOptions.queueEvents](https://github.com/ably/ably-js/commit/757ecb5b81476ed63c0e0e5b232dedb82312f753)
+- [Remove DeprecatedClientOptions.headers](https://github.com/ably/ably-js/commit/d7aaf347d26991b6139bce8260e32c3735c9165c)
+- [Move remaining DeprecatedClientOptions into new type](https://github.com/ably/ably-js/commit/fe3c9ce49df62ffa357dec0843a3f3325ca7c65e) — made it no longer possible to pass `promises` or `maxMessageSize` client options (although I’m not sure they were ever publicly exposed)
+- [Remove deprecated ClientOptions.fallbackHostsUseDefault](https://github.com/ably/ably-js/commit/adfe5992891e7b140696317bf254edc615e05024)
+- [Remove deprecated ability to pass ClientOptions.recover as a boolean](https://github.com/ably/ably-js/commit/399c896445b1505adcdf462f5ff7798dc04b7439)
+- [Remove deprecated ability to pass "xhr" in ClientOptions.transports](https://github.com/ably/ably-js/commit/b8ad229524d433c401c1a3a4cd19b452913068ed)
+- [Remove deprecated RealtimePresence.on/off methods](https://github.com/ably/ably-js/commit/742a981dcac464e417f6e80c9c6674e4c66ec181)
+- [Remove deprecated ability to pass AuthOptions.force property](https://github.com/ably/ably-js/commit/2402dc249d683a5b8d3dd39f89b6be15957cefd4)
+- [Remove deprecated ability to pass flags to RealtimeChannel.attach](https://github.com/ably/ably-js/commit/2b56a434c6d0a81846a29f2d31677dbac0f794b0)
+
+##### Not previously deprecated
+
+TODO decide what to do about not-previously-deprecated stuff (see https://github.com/ably/ably-js/issues/1666) — I think perhaps we should add replacement API into v1, along with deprecation warning
+
+- [Conform to spec for logging configuration](https://github.com/ably/ably-js/commit/eaee6f6ff20f5d38ae2305edf2a7061b799249e3) (`ClientOptions.log` replaced with `logHandler` and  `logLevel` )
+
+#### Removal of other stuff
+
+##### Already deprecated
+
+- [Remove deprecated Auth.authorise method](https://github.com/ably/ably-js/commit/5d3a18ac0f5b3927ed61250532a8a1c334ec6a16)
+- [Remove deprecated forms of calling Crypto.getDefaultParams](https://github.com/ably/ably-js/commit/0f2074ec5d366991238f93a4000f62a360887437)
+
+#### Only for TypeScript users
+
+##### Already deprecated
+
+- [Remove `Realtime < Rest` inheritance in public API](https://github.com/ably/ably-js/commit/69c35f14fd82e8b33f9d88ad78180db3d3acc888)
+- [Fix optionality of `Message` properties](https://github.com/ably/ably-js/commit/4e3733f427fe70754dc36a6a9928182c79e81d72)
+- [Tighten type of publishing methods](https://github.com/ably/ably-js/commit/19a8d475fb892c9b308685ebf015a50d6ba8e9b2)
+- [Add "Abstract" prefix to Types.{Rest, Realtime} names](https://github.com/ably/ably-js/commit/312298a7a95370f149b63ac8751caf8b73e76b2a) — I think this was since changed though; there’s nothing with those names. I’m seeing `RealtimeClient` and `RestClient` interfaces. Ah, yep, changed it in [Rename Abstract* classes to *Client](https://github.com/ably/ably-js/commit/44eae5d4b6010b86c2043edaa4bd83523903d69e)
+- [Remove the Types namespace](https://github.com/ably/ably-js/commit/30f267d8f9f377bde2917cd3f61dd598bbeadb21)
+- [Remove public ChannelModes type](https://github.com/ably/ably-js/commit/04f0f16427c0caab9799b02ee73877f6b71e5ded)
+- [Remove duplicate type names](https://github.com/ably/ably-js/commit/f7e28aa029a64f178c2996c668f4bab878033c03)
+
+##### Not already deprecated
+
+- [Remove `any` from `stats()` param type](https://github.com/ably/ably-js/commit/e524d68946842270a853f50188b27eba00f3add7) — this was already deprecated
+- [removed deprecated unused public types](https://github.com/ably/ably-js/commit/440d89089bbf7c7ee9fb498e62c7ba53691a3d67)
+
+## Migration guide for React Hooks
+
+- A bunch of React hooks changes, the end result of which I think is that there’s a new `ChannelProvider` API which I _think_ is the only way to get access to a channel and hence a breaking change (but need to understand better). **Also, there seem to be no documentation changes to explain any of this.**
+	- [WIP!: `ChannelProvider` implementation draft](https://github.com/ably/ably-js/commit/c6ff4264d00d320e69a250130ac8a8d7bb607401)
+	- [chore: rename `channelToOptions` to show it's internal](https://github.com/ably/ably-js/commit/ab365de3123344c37977089bacf3393006aa3021)
+	- [chore: make `ChannelProvider` mandatory](https://github.com/ably/ably-js/commit/5b7a34034a3ace318df71a029cb91a7028843a53)
+	- [refactor: use React context to store channel instance](https://github.com/ably/ably-js/commit/baf68c809adac1de5e32abb9fa7277eebb7795d2)
+	- [chore: update example App, wording for channel without provider excep…](https://github.com/ably/ably-js/commit/5324354c8f9b3faf071055973c7f255ce7d7ac62)