Propose transpilation guidelines

[dsyme]

A conversation in fsprojects/FSharp.Data.Adaptive#36 made it clear that we should add some guidelines about supporting transpilers.

This is a draft of some guidelines, please discuss below.

[granicz]

As a start to this discussion, consider the comment you made a couple years ago: fsharp/fsharp-compiler-docs#688 (comment)

I see no reason to change that stance and I expect it will be hard to argue otherwise. As a general rule, I would require transpilers to support whatever feature necessary to make subsequent reinterpretation possible without having to litter the code bases of the libraries they are applied on. For WebSharper currently, this is mostly in place already, and any further changes to make that process even less painful are also within easy reach.

And related here, I would also like to point out my growing concern about JS transpilation in general: with efforts around .NET to WASM and .NET on WASM, the relevance JS had for F# web applications is quickly diminishing. I urge everyone to reconsider the F# strategy here and factor this into the decision making when starting new web projects.

[dsyme]

As a start to this discussion, consider the comment you made a couple years ago: fsharp/fsharp-compiler-docs#688 (comment) I see no reason to change that stance and I expect it will be hard to argue otherwise.

Yes, if a transpiler is supported it is better to use feature-specific switches #if NO_FOO_FEATURE rather than #if MYTRANSPILER. The long term cost of maintaining any #if must also absolutely be taken into account. That's the comment I was making there. I will make sure these are in these guidelines.

As a general rule, I would require transpilers to support whatever feature necessary to make subsequent reinterpretation possible without having to litter the code bases of the libraries they are applied on.

Certainly it's good if transpilers support the whole language.

However in these guidelines I don't think it's reasonable to rule out library authors supporting transpilers that have limited features either in library (which nearly all have some limits on) or language (which some have limits on). The choice is really up to library authors. If there's an Erlang transpiler then yes, it won't have full language coverage, but I'm not going to rule out any particular library maintainer deciding to pay the costs of supporting that.

Note that in the context of FSharp.Compiler.Service we have decided not to integrate transpilation. That was our decision in dotnet/fsharp made for a variety of reasons, which match those in the guidelines, primarily CI and maintenance costs - what do we do when CI starts failing.

So please don't think I'm strongly advocating for supporting libraries supporting transpilation. I did make an positive comment in the context of FSharp.Data.Adaptive, but that was just an idle remark knowing that the Aardvark people work in both .NET and Fable. The guidelines here are a more considered.

Re WASM: the merits of different alternative execution substrates is off-topic for the general guidelines, though definitely relevant to people's choices. I will add a general guideline that captures what you want, e.g. "consider the strategic ramifications and network effects of your choice of supported transpilers and execution infrastructure"

[dsyme]

@granicz I've added a couple of additional guidelines based on your feedback above.

[granicz]

My recommendation is that as official guidelines, the text should aim to illustrate points using a neutral viewpoint, and not refer to specific tools. For instance, take the following clause in the current version:

• Consider using an appropriate different namespace, e.g. Fable.Data.Adaptive for transpiled versions of the library.

This might look OK on a first glance to the uninitiated, but it could well have been written years ago and reference FunScript or Pit instead, or any other tool now defunct. While one could propose to periodically revise the guidelines and change such references to the "current recommendation", I believe that would be counterproductive to the community as a whole as the "current recommendation" is highly subjective. Instead, the text could give such examples as {YourTranspiler}.Data.Adaptive.

Following a similar reasoning, I also feel that the reference to a given transpiler with the FSharp.Compiler.Service example you propose to add is out of place. In addition, other forks might appear using different transpilers in the future, triggering a need for an update that otherwise could have been saved if no such example was given. The real value in that example is that users are welcome to fork core libraries to adapt to different transpilers, so perhaps we could/should just say that.

Overall, one would expect not to find subjective opinions or ideas weaved into these guidelines. For instance, you are making a subjective claim that "the execution infratstructure" (sic) needs widespread adoption in industry (what's subjective here is the difficulty of measuring that) or whether other F# users use a tool or not (which again is hard to measure and will most likely be highly biased). For instace, if we look at social media (Twitter, Facebook, blogs, etc.) to try to justify these points, we would find a large volume of the subjective opinions from a relatively small number of people (self-made influencers, freelancers, open source developers, etc.), whereas the opinions of orders of magnitude more professional developers sitting behind corporate desks will be completely absent, simply because they prefer to not be vocal about their opinions for various reasons - thus, overall, the "evidence" drawn from social media we consider correct will be largely wrong. As such, I strongly feel the questions raised in relation in the newly added clause ("Consider the strategic ramifications of ...") don't belong there.

[dsyme]

My recommendation is that as official guidelines, the text should aim to illustrate points using a neutral viewpoint, and not refer to specific tools.

Yes, that's good feedback, I'll adjust

As such, I strongly feel the questions raised in relation in the newly added clause ("Consider the strategic ramifications of ...") don't belong there.

Sure, that's reasonable.

[dsyme]

I've made those adjustments, thanks