Closed cknitt closed 4 years ago
I will discuss this with Cheng today, since there are a lot of open questions on what is officially on the plan. A few things (especially the topic Pipe First vs Pipe Last) feel like they should belong to the Reason language docs (which will hopefully be added as soon as we aligned plans).
@ryyppy True, there should be a section about Pipe First vs. Pipe Last in a more general place in the docs. We can reference that from the Belt and Js docs then.
Nonetheless, we need to explain in the context of the Js namespace why there are currently both Js.Array
and Js.Array2
etc. and what the plan is going forward.
@cknitt Patrick and I had two separate calls with Cheng the last two weeks. He explained that Js.Xxx2
was never supposed to be public and we should not promote it. This was rather something they need for some reason internally.
Personally I have mixed feeling about it, but I suggest we keep aligned with the core team. Consistent messaging is more important.
Proposal:
What do you think? @cknitt @ryyppy
@nikgraf @ryyppy I do not like this at all.
First of all, the biggest question is what is the roadmap? Is it still planned to make all the Js APIs data-first eventually (like Belt already is)? I would strongly suggest to do so, the current mish-mash of data-first and data-last APIs is very confusing for newcomers.
If so, the next question is what to do while this migration to data-first APIs is in progress. Using a data-last API like Js.String with pipe first and the _
functionality feels awkward to me. Personally I'd rather use data-first APIs with the pipe first operator and data-last APIs with the pipe last operator.
Same feeling here, I hope we could quickly have a better situation on this data-first/last. I definitely thing we should go data-first as the pipe first operator is better (from my experience) for inference (I started reason using pipe-last |> but got plenty of situation where the inference was not good and switching to Belt + data-first solved all this kind of problem).
There is a plan to make it data first. Everything will be data first, afaik. The only thing we should accept right now is that there are currently two ways on how to do it:
We could state that xxx2 modules exist and explain how they work, but that they are non-public API. Users can decide if they are taking the risk of breaking changes. I guess for many, they see more value in consistent APIs and will take the cost for refactoring later on (which hopefully won't be too much effort anyways).
There's not much we can 100% recommend, we can only state what's the situation and let ppl know about it. What we can definitely tell is that data-first is here to stay.
There is a plan to make it data first. Everything will be data first, afaik.
🎉 🎉 🎉
The only thing we should accept right now is that there are currently two ways on how to do it: ...
Ok, will try to update the PR accordingly.
(Also cleaned up/unified some minor things with the Belt introduction I wrote previously.)
I hope that the information regarding the Js.Xxx -> Js.Xxx2 migration is accurate, as I have not received any answer to my questions in https://github.com/BuckleScript/bucklescript/issues/2975#issuecomment-542549940.
@ryyppy In the JS docs, the style is currently somewhat broken as the headlines (h2) are invisible.