Libraries and bindings authoring and publishing

[jchavarri]

Just opening a discussion about Melange libraries, authoring, publishing, conventions in naming, tooling, etc. A version of this discussion might end up becoming a section in the melange.re docs site later on, but I thought it'd be good to open it to everyone here for now, in a more public way than Discord chat.

This conversation started a few days ago with a question asked by @mlms13 in Reason Discord:

For publishing melange-compatible bindings to JS libs, is there any guideline on naming, general best practices that people should follow to make sure libraries "feel" relatively consistent, any criteria for putting them in a "community" org vs under my own user (or work account)?
As a consumer of bindings, I think I'd like:

• any easy way to find libraries
• zero-cost unless there's a really good reason to add Reason-specific runtime
• send.pipe over send for binding to methods, but this is not a hill I'll die on
• bonus: maybe some expectation that bindings versions have some relationship to the version of the underlying library? some easy way to know e.g. how safe version changes are and how much work it might be for someone else to contribute an updated version of a binding

Here are some thoughts about those topics and some others:

Finding libraries

For this, once we start publishing in opam, we can use opam "tags" to mark packages with a melange tag, so anyone can easily find them later. The library opam file would include a field like this:

tags: ["melange"]

This allows to find all libraries later on from ocaml.org package search page. For example, here are all pkgs with tag codec: https://ocaml.org/packages/search?q=tag%3A%22codec%22

We can also leverage special "org" tags for packages that are part of melange-community or other orgs, e.g.:

tags: ["melange" "org:melange-community"]

Zero cost bindings

I think I agree with this idea in principle, but it sometimes has gotten a little bit extreme in the past, at the cost of the API ergonomics. In general, I would leave this choice open to the bindings author discretion, users that need to squeeze the extra performance of a few lines of runtime in the bindings can probably look into how the bindings are implemented and remove the runtime if needed?

Pipe last vs pipe first

I also think this is up to the library author discretion, as Melange allows both for backwards compatibility. But considering OCaml supports pipe last |> and Melange tries to stay as close to OCaml as possible, choosing send.pipe seems more appropriate.

Define constraints to npm packages for bindings

We are working on an opam plugin called opam-check-npm-deps. This plugin checks the current opam switch to read all opam files from installed packages, looking for depexts fields that use the npm-version variable together with a version constraint in "npm dependencies style". It then reads the node_modules folder to see if the constraints are satisfied.

For example, the reason-react bindings could define its dependency on the react npm with with something like:

depexts: [
  ["react"] {npm-version = "^16.0.2"}
  ["react-dom"] {npm-version = "^16.0.2"}
]

Or, to simplify:

depexts: [
  ["react" "react-dom"] {npm-version = "^16.0.2"}
]

It will be published in the opam repository this week or the next, any kind of feedback is appreciated!

Package naming

About naming, we are trying to stick with prefixing the name of the package with melange-. Here are some examples (still unpublished in opam, but we use them internally @ Ahrefs):

• https://github.com/ahrefs/melange-react-dnd
• https://github.com/ahrefs/melange-react-virtualized
• https://github.com/ahrefs/melange-react-intl-ppx
• https://github.com/melange-community/melange-json
• https://github.com/melange-community/melange-jest
• https://github.com/melange-community/melange-webapi
• https://github.com/melange-community/melange-fetch

Publishing packages in opam

Publishing in opam public repository involves some steps if one does everything manually. I have found the dune-release tool particularly useful, in combination with this gist from @anmonteiro. Those that have published in opam before, did you use dune-release, manual process or something else?

---

What do you think about the above topics? Would there be other things missing from the publishing perspective for Melange library and bindings authors?