Re: [Caml-list] About contributions to the Standard Library

[Gabriel Scherer <gabriel.scherer@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 5995 bytes --]

In my experience, reviewing propositions for new functions to the standard
library is very delicate and a rather stressful process. I think that
guidelines on how to discuss, review and validate these proposals would
help making it easier. Do we have some, or do we intend to have some in the
short-term future?

What makes standard library additions hard to review is that the review is,
*in essence*, a session in bike-shedding. We can all recognize
bike-shedding and it makes nobody happy, but when doing API design
bike-shedding is very much the point. So standard library addition
discussions, by design, tend to make people frustrated. I think policies on
how to contribute to these discussions, and how decisions will be made,
could help alleviate some of that frustratoin.

For the 4.03 deadline we had a very simple policy: we would only accept
functions whose name and function were completely obvious and
non-objectionable ("map2" for example). If anyone in the discussion had a
reservation about a function, we did not include it. In retrospect, I think
that having agreed on that was an excellent choice, it made it easy to
discuss those proposals.

Now of course this specific policy was only intended short-term, and is
probably too conservative to handle future stdlib changes. Is there a
reasonable relaxation of that policy that people would be willing to agree
on? Or maybe it would be possible to explicit the fact that there are
several kind of contributions, some that fit certain well-defined criteria
(such as the one above: being obvious and completely uncontroversial) and
are expected to be processed/review/decided in due diligence, and some that
are outside these bounds and should be *expected* to devolve into long and
possibly-frustrating discussions?


## Notes

(1) Discussing function names or seemingly-minor API details is not
necessarily an exercise in subjectivity. There are precise (formal) things
that can be said about properties of certain interfaces compared to others,
as we discussed with Daniel Bünzli in a memorable past discussion in
GPR#10. Taking time to make decisions can result in measurably better
designs, and the importance of unit testsuits *and* property testing to
help and structure API design cannot be under-estimated.)


(2) I think part of the stress comes not from the specific status of
standard library (it exists with other libraries), but because of
backward-compatibility requirements: one cannot get it wrong on the first
time. I think this strong requirement is a good choice for the standard
library, despite its costs.


(3) As Daniel pointed out, we need a better understanding of how to make
code written using new stdlib functions compatible with older OCaml
versions. So far we've used ad-hoc solutions on each situation, and it was
barely manageable despite the small number of instances. (Bytes: in
findlib; opaque_identity: clever hack; String ascii functions: no solution).

On Tue, Jun 21, 2016 at 7:56 AM, Damien Doligez <damien.doligez@inria.fr>
wrote:

> Dear Ocaml contributors and users,
>
> I would like to call to your attention the section below,
> which was recently added to the CONTRIBUTING.md file in the
> OCaml source repository.
>
> Have a nice day,
>
> -- Damien
>
>
> ## Contributing to the standard library
>
> Contributions to the standard library are very welcome.  There is some
> widespread belief in the community than the stdlib is somehow "frozen"
> and that its evolutions are mostly driven by the need of the OCaml
> compiler itself.  Let's be clear: this is just plain wrong. The
> compiler is happy with its own local utility functions, and many
> recent additions to the stdlib are not used by the compiler.
>
> Another common and wrong idea is that core OCaml maintainers don't
> really care about the standard library.  This is not true, and won't
> be unless one of the "alternative standard" libraries really gains
> enough "market share" in the community.
>
> So: please contribute!
>
> Obviously, the proposals to evolve the standard library will be
> evaluated with very high standards, similar to those applied to the
> evolution of the surface langage, and much higher than those for
> internal compiler changes (optimizations, etc).
>
> A key property of the standard library is its stability.  Backward
> compatibility is not an absolute technical requirement (any addition
> to/of a module can break existing code, formally), but breakage should
> be limited as much as possible (and assessed, when relevant).  A
> corollary is that any addition creates a long-term support commitment.
> For instance, once a concrete type or function is made public,
> changing the exposed definition cannot be done easily.
>
> There is no plan to extend dramatically the functional domain covered
> by the standard library.  For instance, proposals to include support
> for XML, JSON, or network protocols are very likely to be rejected.  Such
> domains are better treated by external libraries.  Small additions to
> existing modules are much simpler to get in, even more so (but not
> necessarily) when:
>
>   - they cannot easily be implemented externally, or when
>   - they facilitate communication between independent external
>     libraries, or when
>   - they fill obvious gaps.
>
> Of course, standard guidelines apply as well: proper documentation,
> proper tests, portability (yes, also Windows!), good justification for
> why the change is desirable and why it should go into stdlib.
>
> So: be prepared for some serious review process!  But yes, yes,
> contributions are welcome and appreciated.  Promised.
>
>
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
>

[-- Attachment #2: Type: text/html, Size: 6940 bytes --]