Write a migration guide for 1.0

[TheSpyder]

Moving from bs-webapi to rescript-webapi 1.0 won't be a drop-in replacement. We need a migration guide, and I think we need to highlight it at the top of our readme file.

I'm going to make notes in comments to this issue.

[TheSpyder]

Some of the build failures that come up after moving to rescript-webapi are simple, for example swapping document |> Document.createElement("span") to document->Document.createElement("span") is a simple matter of swapping the pipe operator.

However if the pipe operator wasn't used, for example Document.createElement("span", document), it must manually be changed to Document.createElement(document, "span").

[TheSpyder]

Many methods on the node interface - appendChild, removeChild, contains, stuff like that - have the same or similar types for both arguments. So swapping them doesn't trigger a compile error.

We probably need to list these explicitly. In version 2, we will add named arguments... although if they will cause headaches for developers, and they need to edit these lines anyway, perhaps we add them in 1.0 (#49)

[TheSpyder]

The "t first" swap means in 3 places an extra unit argument is required. This is caused by how the type system deals with optional arguments. When a function definition includes optional arguments the final argument must be concrete to resolve whether the intent is to call the function or curry it. The traditional way to achieve this is adding a unit argument.

In these 3 cases, previously the use of "t last" was used as a shortcut to resolve them (via @bs.send.pipe). With the swap to "t first" the optional arguments cannot be resolved so a unit argument is required.

The three APIs are:

• Dom.Window.open_
• Canvas.Canvas2d.fillText
• Canvas.Canvas2d.strokeText

In all 3 cases the unit argument is not emitted, only required by the compiler, using the @ignore tag on the externals.

[DZakh]

@TheSpyder Hi, what are the plans for releasing rescript-webapi@1.0.0?

[TheSpyder]

Sorry, I haven't been a very good steward of this codebase. A year ago I moved across country and I've let other things get in the way since then - we stopped using ReScript at work, so it's now just me on my personal time.

My plan for 1.0 was to get it out and then do a big API update; there are some experimental branches and very old PRs along these lines. I will welcome any contributions.