Update jsx3 migration guide

Author: MoOx

website/docs/migration/jsx3.md

@@ -18,58 +18,30 @@ coupled with our compatibility layer `bs-react-native-jsx3-compat`
 So first,
 
 - be sure that you use `bs-platform@^5.0.1`
-- be sure to use `reason-react` master branch (until 0.7.1 or 0.8 is out) (at
-  least commit
-  [835b90c](https://github.com/reasonml/reason-react/commit/835b90c1c73827632a9819a353a404380724b1d2))
+- ⚠️ be sure to use
+  `"reason-react": "https://github.com/reasonml/reason-react.git#835b90c"`
+  (until 0.7.1 or 0.8 is out)
 - use `react@^16.8.0`
 - add `reason-react-compat@^0.4.0`
 - (if needed, upgrade some deps (eg: `reason-apollo@^0.16.0`))
-- use https://github.com/bloodyowl/upgrade-reason-react
-  - **⚠ Note that if you use `->` operator a lot inside jsx, you will have a lot
-    of bad surpise atm. We are working on improving the script.** Be warned.
-  - if things breaks hard with `❗️️Errored on {somefile}`, that probably
-    because something doesn't please the inlined version of refmt that's in the
-    upgrade script. Things like this
-  ```reason
-    StyleSheet.create(
-      Style.{
-  ```
-  will need to be replaced with
-  ```reason
-  Style.(StyleSheet.create({
-  ```
-  This also require you to adjust the other side of this StyleSheet declaration,
-  so replace
-  ```reason
-      },
-    );
-  ```
-  with
-  ```reason
-      },
-    ));
-  ```
-  Same for very short declarations
-  ```reason
-  StyleSheet.create(Style.{
-  ```
-  will need to be replaced with
-  ```reason
-  Style.(StyleSheet.create({
-  ```
-  And don't forget on the other side... `});` with `}));` Same apply for similar
-  patterns...
+- use https://github.com/bloodyowl/upgrade-reason-react-esy
+
+---
 
 ### Workaround for git usage
 
-- `yarn add https://github.com/reasonml-community/reason-react-native.git#jsx3-migration`
+_If you use released packages, you can skip these steps._
+
+- `yarn add https://github.com/reasonml-community/reason-react-native.git`
 - run a dirty command to get proper setup when using
   `bs-react-native-jsx3-compat`: add as a `prepare` script
   - `"prepare": "ln -sFf ../node_modules/reason-react-native-monorepo/reason-react-native/ ./node_modules",`
 - run `yarn prepare` (this will be run each time you use yarn & will ensure that
   the trick is always around until you actually use released versions of this
   work)
 
+---
+
 Now you can try to compile your code but it's unecessarry. **You might have tons
 of error because `bs-react-native` is full of jsx2** & we just migrated codebase
 to jsx3.
@@ -78,21 +50,21 @@ So please:
 
 - Ensure your project is full jsx3 (`bsconfig.json`:
   `"reason": {"react-jsx": 3},`)
-- Replace `bs-react-native` by `reason-react-native-monorepo/bs-react-native-jsx3`
-  in your `bsconfig.json` (**⚠️ check the
-  [git monorepo trick](https://github.com/reasonml-community/reason-react-native#-usage-from-git-repo)**)
+- Replace `bs-react-native` by `bs-react-native-jsx3` in your `bsconfig.json`
+  (or `reason-react-native-monorepo/bs-react-native-jsx3` for git users, check
+  the
+  [git monorepo trick](https://github.com/reasonml-community/reason-react-native#-usage-from-git-repo)
+  if necessary)
+
+🎉 **Compilation time!**
 
-Compilation time! You should still have some errors, but probably not that much.
+You should still have some errors, but probably not that much.
 
 ## Time to fix remaining errors before everything works™
 
 We did our best here to avoid you having to update/fix your code but there might
 still be some minor stuff to adjust
 
-- you might find some weird error related to fast-pipe swapping code, this can
-  be related to refmt issues, you will have to fix those by hand
-  - eg: `{string_of_int(value)->ReasonReact.string}` turned into
-    `{string_of_int;value->ReasonReact.string}`
 - check `children` errors and remove
   `let children = React.Children.toArray(children);` that might have beed added
   without being necessary
@@ -102,9 +74,9 @@ still be some minor stuff to adjust
 
 ### Notes about `ReasonReact.wrapJsForReason` & `ReasonReact.wrapReasonForJs`
 
-With reason-react 0.7 & new api, code produced is just normal react component.
-So this things are not necessary anymore but are not handled by the script we
-used.
+With reason-react 0.7 & new api, JavaScript code produced is just normal React
+code. So this things are not necessary anymore but are not handled by the script
+we used.
 
 So you might need to remove those things & replace them with vanilla React code
 
@@ -120,7 +92,7 @@ So you might need to remove those things & replace them with vanilla React code
 When you don't have any errors, just compile & enjoy jsx3. You can even add
 `reason-react-native` to your `bsconfig.json` `bs-dependencies` & use it right
 away with
-[awesome hooks](https://reasonml.github.io/reason-react/docs/en/components) 🥳
+[awesome hooks](https://reasonml.github.io/reason-react/docs/en/components) !
 
 Here are some commits that might help you
 
@@ -129,17 +101,17 @@ Here are some commits that might help you
 
 🙏 _Please do not hesitate to share your experience with the migration._ If the
 source is open, post your commit here, it could help someone without you even
-knowing 🤷‍♂️
+knowing 🤷‍
 
-## Need help to migrate?
+## Need help to migrate ?
 
 If you struggle with it & have questions,
 [reach us on our discord server](https://discord.gg/eaU3Z6Q)
 
 ---
 
-**If you are reading this, you can assume you are done & ready to work on other
-things, like feature & bugfix for your product.**
+🎉 **If you are reading this, you can assume you are done & ready to work on
+other things, like feature & bugfix for your product.**
 
 ---
 
@@ -148,47 +120,69 @@ things, like feature & bugfix for your product.**
 You can do some easy stuff to cleanup your codebase now that everything is
 working and that you are ready to use reason-react 0.7:
 
-- Easy replacement
-  - `ReasonReact.string` => `React.string`
-  - `ReasonReact.array` => `React.array`
-  - `ReasonReact.null` => `React.null`
-  - `ReasonReact.reactElement` => `React.element`
-  - ...
-- More tricky ones: you can probably remove lot of unecessary wrapping for
-  stateless component that don't use the lifecycle
-  ```reason
-    ReactCompat.useRecordApi({
-        ...component,
-        render: _self => {
-  ```
-  Can be replaced with
-  ```reason
-  ({{
-  ```
-  And
-  ```reason
-    ReactCompat.useRecordApi({
-        ...component,
-        render: _self =>
-  ```
-  Can be replaced with
-  ```reason
-  ({
-  ```
-  At this point, the 2 replacements above have generated syntax error, so you
-  should try to replace
-  ```reason
-  ,
-    });
-  ```
-  with
-  ```reason
+### Easy replacement
+
+- `ReasonReact.string` => `React.string`
+- `ReasonReact.array` => `React.array`
+- `ReasonReact.null` => `React.null`
+- `ReasonReact.reactElement` => `React.element`
+- ...
+
+### More tricky ones
+
+You can probably remove lot of unecessary wrapping for stateless component that
+don't use the lifecycle
+
+```reason
+  ReactCompat.useRecordApi({
+      ...component,
+      render: _self => {
+```
+
+Can be replaced with
+
+```reason
+({{
+
+```
+
+And
+
+```reason
+  ReactCompat.useRecordApi({
+      ...component,
+      render: _self =>
+```
+
+Can be replaced with
+
+```reason
+({
+```
+
+At this point, the 2 replacements above have generated syntax error, so you
+should try to replace
+
+```reason
+,
   });
-  ```
-  At this point, you should be able to drop some
-  `let component = ReasonReact.statelessComponent...` too, since some won't be
-  used anymore thanks to the last removal step we did.
+```
+
+with
+
+```reason
+});
+
+```
+
+At this point, you should be able to drop some
+`let component = ReasonReact.statelessComponent...` too, since some won't be
+used anymore thanks to the last removal step we did.
 
 Now rely on refmt to get a cleaner code and you are good to go!
 
-Do not hesitate to share more tips & tricks to ease the migration! Don't be shy!
+---
+
+Do not hesitate to share more tips & tricks to ease the migration!
+
+[Don't be shy!](https://github.com/reasonml-community/reason-react-native/issues/new?title=JSX3+migration+trick&body=Hey%20I%20have%20a%20trick%20that%20I%20can%20share%20with%20you%20to%20ease%20jsx3%20migration%3A)