From 5ab88e4a0a04b88da7000f894fa989a0ab8a7a3a Mon Sep 17 00:00:00 2001 From: Don Syme Date: Fri, 4 Oct 2019 11:43:38 +0100 Subject: [PATCH 1/3] Propose transpilation guidelines --- _posts/2014-09-19-fsharp-libraries.md | 33 +++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/_posts/2014-09-19-fsharp-libraries.md b/_posts/2014-09-19-fsharp-libraries.md index 199539a..552ba16 100644 --- a/_posts/2014-09-19-fsharp-libraries.md +++ b/_posts/2014-09-19-fsharp-libraries.md @@ -9,6 +9,11 @@ subtitle: Naming, Engineering and General Advice > Naming, Engineering and General Advice +## Author + +Don Syme, with advice from various contributors to F# Core Engineering discussions. + +Originally drafted September 2014, with subsequent minor updates. ## Contents {:.no_toc} @@ -17,17 +22,16 @@ subtitle: Naming, Engineering and General Advice ## Introduction -One of the goals of F# Core Engineering is to help ensure best engineering practices in public-facing F# components and packages. +One of the historic goals of the "F# Core Engineering" group is to help ensure best engineering practices in public-facing F# components and packages. -In this post we outline some recommended guidelines for naming and engineering for F# projects, packages and namespaces. -We particularly focus on open projects such as those in the [F# Community Projects](http://fsharp.org/community/projects/) list or +In this document we capture some recommended guidelines for naming and engineering for F# projects, packages and namespaces. This is based on how things stood in 2014, and we have continued to update these with minor modifications. We particularly focus on open projects such as those in the [F# Community Projects](http://fsharp.org/community/projects/) list or [packages in NuGet for an "FSharp" search](http://www.nuget.org/packages?q=fsharp). These are recommendations - they are not hard-and-fast rules, and are offered for discussion amongst F# developers. If you would like to discuss these guidelines or suggest modifications, please [edit this file on GitHub and submit a pull request](https://github.com/fsharp/fsharp.github.io/edit/master/_posts/2014-09-19-fsharp-libraries.md). -There is agreement on the following: +In discussions, there has been agreement on the following: 1. FSharp.* projects should be high-quality or trending **rapidly** in that direction. Ideally any packages and code under the FSharp.* namespace should be of sufficient quality to be considered @@ -169,6 +173,27 @@ or other community forums.
+## Transpiling Guidelines + +
+ +Some F# libraries are candidates for cross-compilation using F# transpiler tools such as Fable and WebSharper. Other transpilers for other targets may also be developed over time. + +The following are draft guidelines for adding support for transpilation, based on information available in 2019. + +* Consider supporting transpilation by one or more alternative toolchains. It is not required or obligatory. + +* Do ensure that the qualities of the library are not diminished significantly, e.g. API design, documentation and performance. + +* Do be positive to contributions which add support and testing for other transpilers. However there is no obligation to support any particular transpiler. + +* Do add CI testing for the transpilation. + +* Consider using an appropriate different namespace, e.g. `Fable.Data.Adaptive` for transpiled versions of the library. + +* Consider the maintenance burden of the necessary `#if` when making your decisions, including the long-term maintenance by other contributors. + + ## Engineering Guidelines
From d8e040ac6d57aae21d9f6eb0f6a894abafdd06f3 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 10 Oct 2019 10:56:23 +1000 Subject: [PATCH 2/3] Update 2014-09-19-fsharp-libraries.md --- _posts/2014-09-19-fsharp-libraries.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/_posts/2014-09-19-fsharp-libraries.md b/_posts/2014-09-19-fsharp-libraries.md index 552ba16..de500b4 100644 --- a/_posts/2014-09-19-fsharp-libraries.md +++ b/_posts/2014-09-19-fsharp-libraries.md @@ -130,11 +130,17 @@ Use the following prefixes where possible, rather than inventing new ones: - `FSharp.Control`: Functionality related to control flow, such as asynchronous programming, message passing, event-based programming, reactive programming, and similar + - `FSharp.Data`: Types related to data access, data schema, and similar + - `FSharp.Text`: Text processing, formating, printing, or similar functionality + - `FSharp.Azure`: Types related to cloud computing on the Azure plattform. + - `FSharp.AWS`: Types related to cloud computing on the AWS plattform. + - `FSharp.Compiler`: Functionality relating to compilation of F# + - `FSharp.Core`: Use sparingly. Typically required for helper types required by incubation of compiler features For example, a library like "FSharp.Actor" might be better renamed to "FSharp.Control.Actor". Similarly, "FSharp.Reactive" @@ -189,10 +195,17 @@ The following are draft guidelines for adding support for transpilation, based o * Do add CI testing for the transpilation. +* Do use feature-specific switches `#if NO_FOO_FEATURE` rather than `#if MYTRANSPILER`. + +* Do assess the quality of the transpilation tool, and the degree of support for language and library. + * Consider using an appropriate different namespace, e.g. `Fable.Data.Adaptive` for transpiled versions of the library. * Consider the maintenance burden of the necessary `#if` when making your decisions, including the long-term maintenance by other contributors. +* Consider the strategic ramifications and network effects of your choice of supported transpilers and execution infrastructure. Are other F# users and contributors using these tools? Will the resulting ecosystem be viable? Does the execution infratstructure having growing and widespread adoption in industry? + +As an example, as of 2019 the `dotnet/fsharp` repository has decided not to support transpilation for the `FSharp.Compiler.Service` library component. However, a separate fork of that repository is maintained by one of the contributors to a particular transpiler (Fable). ## Engineering Guidelines From d9f363ab4d6148372151d7010d72b53c251c1cab Mon Sep 17 00:00:00 2001 From: Don Syme Date: Fri, 18 Oct 2019 16:33:25 +1100 Subject: [PATCH 3/3] Update 2014-09-19-fsharp-libraries.md --- _posts/2014-09-19-fsharp-libraries.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/_posts/2014-09-19-fsharp-libraries.md b/_posts/2014-09-19-fsharp-libraries.md index de500b4..4f0cde0 100644 --- a/_posts/2014-09-19-fsharp-libraries.md +++ b/_posts/2014-09-19-fsharp-libraries.md @@ -199,13 +199,11 @@ The following are draft guidelines for adding support for transpilation, based o * Do assess the quality of the transpilation tool, and the degree of support for language and library. -* Consider using an appropriate different namespace, e.g. `Fable.Data.Adaptive` for transpiled versions of the library. +* Consider using an appropriate different namespace, e.g. `Fox.Collections.Rapid` for transpiled version of the (hypothetical) `FSharp.Collections.Rapid` library. * Consider the maintenance burden of the necessary `#if` when making your decisions, including the long-term maintenance by other contributors. -* Consider the strategic ramifications and network effects of your choice of supported transpilers and execution infrastructure. Are other F# users and contributors using these tools? Will the resulting ecosystem be viable? Does the execution infratstructure having growing and widespread adoption in industry? - -As an example, as of 2019 the `dotnet/fsharp` repository has decided not to support transpilation for the `FSharp.Compiler.Service` library component. However, a separate fork of that repository is maintained by one of the contributors to a particular transpiler (Fable). +As an example, as of October 2019 the `dotnet/fsharp` repository has decided not to support transpilation for the `FSharp.Compiler.Service` library component. However, some transpilers maintain separate forks of that repository. ## Engineering Guidelines