-
Notifications
You must be signed in to change notification settings - Fork 55
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
wip add structure of migration guide
- Loading branch information
1 parent
99a8b1f
commit 9a3cfaf
Showing
1 changed file
with
132 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |