Preparations for the BuckleScript v7 transition

[ryyppy]

This issue is used to keep track of important tasks to make BuckleScript v7 (OCaml 4.06 based version) the default package on npm.

Transition Philosophy

As soon as BS@6 is live, every user should be able to just use our migration guides to upgrade their existing BS@5 based projects to the newest versions. For the most important tools, there should be an equivalent release for handling 4.06 based compile artifacts.

Those tools are mostly PPXes which are based on the 4.02 Parsetree. Our recommendation for PPX maintainers:

• Increase the major version
• Upgrade to the 4.06 Parsetree
• Release the new package to npm, add notes on which major release is intended for which BS version and how to install it for each platform
• Drop support for 4.02, since BS@5 (don't offer adding features for this version)

As a proper example, check out genType. GenType introduced a detached 4_02 branch so it can still provide crucial bug fixes for 4.02 based versions, but it will not provide any new features to make sure users upgrade soon and we can deprecate 4.02 once in for all. It uses the v2.* versions for BS@5 releases, and v3.* for BS@6.

Update: Gentype already dropped the workflow for a 4_02 hotfix-branch completely, since it is too much effort rebasing the diffs

PPX Upgrade tasks

This is a non-exhaustive list of tools which need to be handled, otherwise a lot of people will be stuck (please let me know if you know of any other tools):

• genType
• [] graphql_ppx
• graphql_ppx_re
  Currently forked in https://github.com/baransu/graphql_ppx_re
  Could be moved to a different domain and renamed.
  Example conversion PR: Build with Bucklescript 6.2.1 based on OCaml 4.6.1. pupilfirst/pupilfirst#103.
• bs-let
• decco
  Updated the ppx to support (only) BuckleScript 6.x: https://github.com/reasonml-labs/decco
• bs-emotion-ppx
• ppx_bs_css
• bs-deriving
• bs-log
• bs-material-ui-ppx

A ticked box means that:

• The project supports 4.06
• The package is released on npm
• Has proper instructions on how to install it for BS6
• Has clear communicated maintainers (hint: @reasonml-community / @reasonml-labs org)
• Has been tested with existing projects

Editor Plugin Tasks

• merlin-lsp works with BS@6
• reason-vscode works with BS@6
• reasoml-idea-plugin

BuckleScript v7 Migration Guide

For the official transition, we should prepare a migration guide which communicates:

• All the benefits we get from 4.06 (e.g. language features such as "inline records in variants")
• Explanations on why it is important to deprecate 4.02
• Notes on current refmt version
• Notes that the new version was tested properly and will not cause any troubles with existing Reason source code or Editor plugins
• A section for ppx maintainers (as listed above, but more thorough)
• A section for users on BS@5 (including a list of npm install commands for important dependencies)
• The migration guides should be part of the docs section for easy discovery.
• Migration Guide PR

Since v7 comes with the new records-as-objects feature, we will need to update the Object related docs section as well. (See PR).

Revamp the BuckleScript Object documentation

Pending PR: https://github.com/BuckleScript/bucklescript.github.io/pull/184

• Add docs for record-as-objects
• Refactor Object / Object 2 docs to something more meaningful and communicate

Making it public

We should make sure to communicate the switch on every channel:

• reasonml Twitter
• reasonassoc Twitter
• Discord: (maybe with a newly created announcement channel?)
• reasonml.chat

\cc @anmonteiro @baransu

[swuecho]

PPX Upgrade tasks

• bs-deriving

[cristianoc]

Thanks @swuecho. Added above.

[gaku-sei]

@ryb73 has updated their ppx to support (only) BuckleScript 6.x: rescript-labs/decco@2d68883

Also graphql_ppx being (unofficially) deprecated, we can probably list only graphql_ppx_re (which already supports BuckleScript 5.x and 6.x).

[cristianoc]

@gaku-sei I have update the description on top.

[alex35mil]

• bs-log

[cristianoc]

Thanks @alexfedoseev , added.

[Coobaha]

• reasoml-idea-plugin

[cristianoc]

@Coobaha thank -- added above.
Btw would you know how extensive the plugin is? Asking as it might be more complex than a little PPX.

[Coobaha]

@Coobaha thank -- added above.
Btw would you know how extensive the plugin is? Asking as it might be more complex than a little PPX.

Cc @giraud

I guess it should just work, but thought that it is worth to add it to the list. Will also be happy to test things out

[giraud]

@cristianoc plugin is ready since v0.76 (although I found there is a small update to release to adapt it to bs-6.2.1)

[cristianoc]

@giraud great thanks. Once a version compatible with bs 6.2.1 is released, I'll update the description on top.

[ozanmakes]

PPX Upgrade tasks

• bs-deriving

bs-deriving works with BuckleScript v6 (tested with version "44.1.0")

Side note: Same version of reason-macros works with both v5 and v6. I'm curious how this works? Until now I was never able to use the same ppx binary on different AST versions

[cristianoc]

@osener thanks for the uppdate.

For reason-macros see ocaml-migrate-parsetree in https://github.com/jaredly/reason-macros/blob/master/src/dune#L5.

[ozanmakes]

Ah thanks. I had forward-compatibility in mind when I wrote that, but of course OCaml 4.06 AST is nothing new.

[ryyppy]

let_anything is now bs-let and is advertised as an experimental ppx. Thanks to @mrmurphy for relocating the repo to a shared organisation! Thanks to @anmonteiro for making it BS6 ready!

[ryyppy]

decco has been moved to @reasonml-labs to share responsibility: https://github.com/reasonml-labs/decco

[alex35mil]

shakacode/rescript-logger#12

bs-log is updated and published as bs-log@next. The only thing that stops me from publishing it as latest is that I can't test installation on Windows machine. I'd really appreciate if anyone could help me with it.

[RasmusKlett]

lenses-ppx might be worth mentioning in the upgrade guide, as it is used in the beautiful ReForm library. According to their Readme, I think they support v7.

[studious]

There is also ppx6 for https://github.com/jsiebern/bs-material-ui/tree/master/public/bs-material-ui-ppx