Proposed guidelines on F# packages and projects

[dsyme]

This is a set of proposed project and pakage guidelines, including naming, software engineering and general advice. Discussion about the guidelines can be made in this github issue and by notes on the text. I will also broaden the discussion to the F# open source list after a few initial iterations.

The draft is visible here: http://dsyme.github.io/2014/09/19/fsharp-libraries.html

Specific comments on this thread, general disucssion here: #14

[dsyme]

Thanks, fixed

[ReedCopsey]

Regarding 2. in the header (don't pollute FSharp.* namespace) - this goal seems to contradict, at least partly, the second naming guideline. Would it make more sense to propose an "experimental" top level namespace, and suggest switching to FSharp.* at a point in time when the library meets the goals of 1 &4? It'd be a breaking change, but so is moving from FSharp...Experimental to FSharp.., which is recommended later. My concern here is, over time, having a lot of "FSharp..Experimental.*" libraries that never leave experimental stage, effectively "polluting" FSharp..

Regarding the 2nd level namespace guidelines:

• Should this include a list of the "preferred" namespaces, with a short summary of what type of content belongs in each? Placing this in here might help with consistency over time, especially as the way its currently worded is more of a loose guideline. This could also be written as a separate page and linked from here, which might be nice, as it'd effectively be "documentation" of the thought process behind the 2nd level namespace naming guidelines.
• Should FSharp.Core be included here? It does seem like this is not a great namespace for community created libraries. Things that extend functionality of core seem like they'd be better off in another prefix. It almost seems like "Core" should be called out as reserved/do not use.

[dsyme]

Re 1 - my impression is that using "experimental.FSharp.*" or indeed any Experimental tag greatly decreases the level of early engagement, and people just don't seem to like doing it. We had quite a lot of feedback like that when we last suggested "Experimental".

I think incubating FSharp.* is probably OK if used in combination with other mechanisms such as

• labelling packages as beta/pre-release
• using "alpha" or "beta" in version numbers
• using low version numbers
• making the true status of the project clear in docs
• actively hiding projects and packages which are no longer active

[dsyme]

Re 2nd level namespace guidelines - yes, agreed on both points (though there maybe things that really, really fit in core, e.g. if incubating a compiler feature that needs compiler helperrs). Could you send a PR with a list of 2nd level namespaces add? I think including it here is right.

[ReedCopsey]

Perhaps then there should be some guideline around the incubation/beta/pre-release phase and documentation? Something like:

Guideline: Clearly label project status prior to release

Projects, packages and tools using the FSharp.* top level namespace should clearly and prominently label their status in all documentation during the project's early phases of development. Projects should use version numbers below 1.0 to denote pre-release status, and clearly label their status as "Alpha" when the project is still lacking features or functionality required for widespread usage, and "Beta" prior to adequate usage and testing to be considered a mature package.

[dsyme]

@ReedCopsey - Yes, agreed, could you add that? thx

[ReedCopsey]

@dsyme I believe that PR should address both issues.

[rneatherway]

I like this proposal. I also agree that the .Experimental namespace is likely to put people off, and trying to keep a strict approach to labelling of prelease versions is probably better for engagement.

How should we hide projects that are no longer active? Once they are on NuGet I'm not sure we can do better than emailing the author.

[sergey-tihon]

As an alternative to .Experimental namespace we can create official fsprojects NuGet channel on myget.org for projects in early stage. And publish them on NuGet when they will be ready to use.

The same approach uses Asp.Net team and I love the idea!
In this case we can insert package publishing directly in build script and publish package after every commit/PR.

// cc @forki @fsgit @ReedCopsey

[dsyme]

Can you create a PR with that as a recommendation?

[dsyme]

I jotted down some notes about core v. non-core project management here: #19