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

[Junsong Li <ljs.darkfish@gmail.com>]

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

Thanks for calling it out.

Well, this actually confuses me a bit. Is the ultimate goal for evolving
the builtin library another "Batteries"? I ask this because it does not
sound like you're actually calling for a battery-included stdlib.

If not, here is my second question: Why now? What's the problem for current
stdlib?

Thanks.


On Tue, Jun 21, 2016 at 11:48 PM, Gabriel Scherer <gabriel.scherer@gmail.com
> wrote:

> 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: 7798 bytes --]