[Caml-list] Flambda/compiler walkthrough + modularity

[Caml-list] Flambda/compiler walkthrough + modularity

[Yotam Barnoy]

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

Thank you so much to everyone involved with Flambda (OcamlPro, Jane Street,
and all the people who labored to make it happen). I'm so excited to have
such an awesome framework arrive in OCaml.

I have a question, and then a suggestion.

Is Flambda organized in such a modular way that we can add optimizations
over time? It seems to me that now that we have set the precedent for
having the AST in cmx files and have an interface for using that AST, the
sky is the limit in terms of optimizations.

The bigger issue I have is the following: I have long struggled with
grokking the codebase. A shortage of time has made it difficult, especially
because most of the codebase isn't as well documented as Flambda is. Some
parts, such as byte_run's C files, are quite simple, but other parts (in
particular the typechecker) are definitely trickier.

While thinking about the best way to learn the new Flambda code in the
minimal amount of time, I thought to myself, "wouldn't it be amazing to
have Pierre Chambart and Mark Shinwell just do a video walkthrough of their
code". And then I thought about the rest of the codebase, about Jacques
Garrigue doing a walkthrough of the typechecker code, and each expert(s)
talking about the parts they know really well, and about how amazing it
would be if we had this resource on youtube. It would be the ultimate form
of documentation by the foremost experts on aspects OCaml, welcoming
programmers to contribute to the OCaml compiler in the easiest way possible.

A step further would be if this was done on Twitch or some similar live
broadcasting platform, so people could actually ask live questions as the
session took place. The resulting video would be posted to youtube.

What do you guys think?

-Yotam

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

Re: [Caml-list] Flambda/compiler walkthrough + modularity

[Mark Shinwell]

Adding a new optimisation to Flambda can be straightforward, in
particular if it's a stand-alone global pass.  However, this doesn't
relieve you from problems associated with phase ordering, which can be
problematic to deal with.

If, however, the optimisation relies on something (just to pick an
example) such as the approximations computed during simplification
then it may be harder.  Things like this probably need to hook
directly into the simplifier, which is rather more involved.  We've
had some initial thoughts about returning the approximations as the
"types" of Flambda terms, which might make things more easily modular
in this area.

The idea of a talk is an interesting one, although I think for the
moment it would be a better use of our time to improve the
documentation within the code (which we are planning to do before the
release).  Also, given this is the first version, it's quite likely
there will be significant changes in the next couple of releases which
might make such a talk get out of date quite quickly.  It's perhaps
something we should consider doing after that.

Mark

On 11 March 2016 at 17:04, Yotam Barnoy <yotambarnoy@gmail.com> wrote:
> Thank you so much to everyone involved with Flambda (OcamlPro, Jane Street,
> and all the people who labored to make it happen). I'm so excited to have
> such an awesome framework arrive in OCaml.
>
> I have a question, and then a suggestion.
>
> Is Flambda organized in such a modular way that we can add optimizations
> over time? It seems to me that now that we have set the precedent for having
> the AST in cmx files and have an interface for using that AST, the sky is
> the limit in terms of optimizations.
>
> The bigger issue I have is the following: I have long struggled with
> grokking the codebase. A shortage of time has made it difficult, especially
> because most of the codebase isn't as well documented as Flambda is. Some
> parts, such as byte_run's C files, are quite simple, but other parts (in
> particular the typechecker) are definitely trickier.
>
> While thinking about the best way to learn the new Flambda code in the
> minimal amount of time, I thought to myself, "wouldn't it be amazing to have
> Pierre Chambart and Mark Shinwell just do a video walkthrough of their
> code". And then I thought about the rest of the codebase, about Jacques
> Garrigue doing a walkthrough of the typechecker code, and each expert(s)
> talking about the parts they know really well, and about how amazing it
> would be if we had this resource on youtube. It would be the ultimate form
> of documentation by the foremost experts on aspects OCaml, welcoming
> programmers to contribute to the OCaml compiler in the easiest way possible.
>
> A step further would be if this was done on Twitch or some similar live
> broadcasting platform, so people could actually ask live questions as the
> session took place. The resulting video would be posted to youtube.
>
> What do you guys think?
>
> -Yotam

Re: [Caml-list] Flambda/compiler walkthrough + modularity

[Goswin von Brederlow]

On Fri, Mar 11, 2016 at 12:04:17PM -0500, Yotam Barnoy wrote:
> While thinking about the best way to learn the new Flambda code in the
> minimal amount of time, I thought to myself, "wouldn't it be amazing to
> have Pierre Chambart and Mark Shinwell just do a video walkthrough of their
> code". And then I thought about the rest of the codebase, about Jacques
> Garrigue doing a walkthrough of the typechecker code, and each expert(s)
> talking about the parts they know really well, and about how amazing it
> would be if we had this resource on youtube. It would be the ultimate form
> of documentation by the foremost experts on aspects OCaml, welcoming
> programmers to contribute to the OCaml compiler in the easiest way possible.
> 
> A step further would be if this was done on Twitch or some similar live
> broadcasting platform, so people could actually ask live questions as the
> session took place. The resulting video would be posted to youtube.
> 
> What do you guys think?
> 
> -Yotam

I would watch that.

MfG
	Goswin

Re: [Caml-list] Flambda/compiler walkthrough + modularity

[Gabriel Scherer]

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

A nice quality of in-code comments that a video session does not have is
locality: the explanations are closed to the explainees, so hopefully they
can evolve in synch. Another nice quality (shared with blog posts) is that
it can be proposed by third-parties and crowd-sourced with moderate
efficiency: you can help document the OCaml implementation by sending a
pull-request with comments on the parts you fought to understand.

This has notably been done by Alain Frisch for the parsetree representation
during the 4.01 development phase, and recently (4.03 development cycle,
GPR#310) in types.mli and typedtree.mli by Frédéric Bour, Gabriel Radanne
and Thomas Refis, with helpful feedback from Alain Frisch and Jacques
Garrigue.

Anyone can help by submitting their own contribution to
documentation-as-comments.

On Mon, Mar 14, 2016 at 11:36 AM, Goswin von Brederlow <goswin-v-b@web.de>
wrote:

> On Fri, Mar 11, 2016 at 12:04:17PM -0500, Yotam Barnoy wrote:
> > While thinking about the best way to learn the new Flambda code in the
> > minimal amount of time, I thought to myself, "wouldn't it be amazing to
> > have Pierre Chambart and Mark Shinwell just do a video walkthrough of
> their
> > code". And then I thought about the rest of the codebase, about Jacques
> > Garrigue doing a walkthrough of the typechecker code, and each expert(s)
> > talking about the parts they know really well, and about how amazing it
> > would be if we had this resource on youtube. It would be the ultimate
> form
> > of documentation by the foremost experts on aspects OCaml, welcoming
> > programmers to contribute to the OCaml compiler in the easiest way
> possible.
> >
> > A step further would be if this was done on Twitch or some similar live
> > broadcasting platform, so people could actually ask live questions as the
> > session took place. The resulting video would be posted to youtube.
> >
> > What do you guys think?
> >
> > -Yotam
>
> I would watch that.
>
> MfG
>         Goswin
>
> --
> 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: 3032 bytes --]

Re: [Caml-list] Flambda/compiler walkthrough + modularity

[Yotam Barnoy]

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

On Mon, Mar 14, 2016 at 8:30 AM, Gabriel Scherer <gabriel.scherer@gmail.com>
wrote:

> A nice quality of in-code comments that a video session does not have is
> locality: the explanations are closed to the explainees, so hopefully they
> can evolve in synch. Another nice quality (shared with blog posts) is that
> it can be proposed by third-parties and crowd-sourced with moderate
> efficiency: you can help document the OCaml implementation by sending a
> pull-request with comments on the parts you fought to understand.
>
> This has notably been done by Alain Frisch for the parsetree
> representation during the 4.01 development phase, and recently (4.03
> development cycle, GPR#310) in types.mli and typedtree.mli by Frédéric
> Bour, Gabriel Radanne and Thomas Refis, with helpful feedback from Alain
> Frisch and Jacques Garrigue.
>
> Anyone can help by submitting their own contribution to
> documentation-as-comments.
>
>
This is absolutely true, and I'm extremely grateful to all who commented --
the results are wonderful. The barriers to entry in this case, however, are
knowledge, quality and effort. By contrast, Jacques Garrigue (sorry for
picking on you Jacques) recording a session off the cuff on his laptop as
he casually steps through the code in his editor (he wouldn't even need a
webcam) and then uploading it to youtube would be a tremendous resource in
and of itself.

Another idea is that we develop a protocol for doing precisely this kind of
evolutionary crowdsourced commenting, but take the initial barrier out of
it.  Suppose that we allowed opening PRs on random files in the codebase. I
(or others) would ask questions about functions I didn't understand, and
other people would step up and explain them. Eventually, there might be
some documentation and clarification to add to the code. This would require
tolerance of 'unhelpful' and question-based documentation PRs. There might
be some very basic questions in there. We could add a specific tag, so
these PRs aren't closed prematurely (they could take a while). Would that
be ok?

-Yotam


> On Mon, Mar 14, 2016 at 11:36 AM, Goswin von Brederlow <goswin-v-b@web.de>
> wrote:
>
>> On Fri, Mar 11, 2016 at 12:04:17PM -0500, Yotam Barnoy wrote:
>> > While thinking about the best way to learn the new Flambda code in the
>> > minimal amount of time, I thought to myself, "wouldn't it be amazing to
>> > have Pierre Chambart and Mark Shinwell just do a video walkthrough of
>> their
>> > code". And then I thought about the rest of the codebase, about Jacques
>> > Garrigue doing a walkthrough of the typechecker code, and each expert(s)
>> > talking about the parts they know really well, and about how amazing it
>> > would be if we had this resource on youtube. It would be the ultimate
>> form
>> > of documentation by the foremost experts on aspects OCaml, welcoming
>> > programmers to contribute to the OCaml compiler in the easiest way
>> possible.
>> >
>> > A step further would be if this was done on Twitch or some similar live
>> > broadcasting platform, so people could actually ask live questions as
>> the
>> > session took place. The resulting video would be posted to youtube.
>> >
>> > What do you guys think?
>> >
>> > -Yotam
>>
>> I would watch that.
>>
>> MfG
>>         Goswin
>>
>> --
>> 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: 4961 bytes --]

Re: [Caml-list] Flambda/compiler walkthrough + modularity

[Hendrik Boom]

On Mon, Mar 14, 2016 at 09:51:59AM -0400, Yotam Barnoy wrote:
> On Mon, Mar 14, 2016 at 8:30 AM, Gabriel Scherer <gabriel.scherer@gmail.com>
> wrote:
> 
> > A nice quality of in-code comments that a video session does not have is
> > locality: the explanations are closed to the explainees, so hopefully they
> > can evolve in synch. Another nice quality (shared with blog posts) is that
> > it can be proposed by third-parties and crowd-sourced with moderate
> > efficiency: you can help document the OCaml implementation by sending a
> > pull-request with comments on the parts you fought to understand.

The main problem a technical writer faces in documenting someone 
else's software is to understand it.  Without that, he might produce 
elegant documentation that looks good but is utterly useless.

Would such a recording bw useful to a documentatino writer?  Possibly 
even one who writes comments to include in the code?

As ever, may I suggest people look at the Trestle documentation at 
http://www.std.org/~msm/common/SRC-RR-068.pdf as an 
example of how good machine-generated documentation can be?

Of course this takes care and attention whe writing the comments in 
the code.  nd, presumably, a competent program to covert thsoe 
comments into a well-orgnnised volume.

> >
> > This has notably been done by Alain Frisch for the parsetree
> > representation during the 4.01 development phase, and recently (4.03
> > development cycle, GPR#310) in types.mli and typedtree.mli by Frédéric
> > Bour, Gabriel Radanne and Thomas Refis, with helpful feedback from Alain
> > Frisch and Jacques Garrigue.
> >
> > Anyone can help by submitting their own contribution to
> > documentation-as-comments.
> >
> >
> This is absolutely true, and I'm extremely grateful to all who commented --
> the results are wonderful. The barriers to entry in this case, however, are
> knowledge, quality and effort. By contrast, Jacques Garrigue (sorry for
> picking on you Jacques) recording a session off the cuff on his laptop as
> he casually steps through the code in his editor (he wouldn't even need a
> webcam) and then uploading it to youtube would be a tremendous resource in
> and of itself.
> 
> Another idea is that we develop a protocol for doing precisely this kind of
> evolutionary crowdsourced commenting, but take the initial barrier out of
> it.  Suppose that we allowed opening PRs on random files in the codebase. I

PR? I donn't know the acronym.

> (or others) would ask questions about functions I didn't understand, and
> other people would step up and explain them. Eventually, there might be
> some documentation and clarification to add to the code. This would require
> tolerance of 'unhelpful' and question-based documentation PRs. There might
> be some very basic questions in there. We could add a specific tag, so
> these PRs aren't closed prematurely (they could take a while). Would that
> be ok?
> 
> -Yotam
> 
> 
> > On Mon, Mar 14, 2016 at 11:36 AM, Goswin von Brederlow <goswin-v-b@web.de>
> > wrote:
> >
> >> On Fri, Mar 11, 2016 at 12:04:17PM -0500, Yotam Barnoy wrote:
> >> > While thinking about the best way to learn the new Flambda code in the
> >> > minimal amount of time, I thought to myself, "wouldn't it be amazing to
> >> > have Pierre Chambart and Mark Shinwell just do a video walkthrough of
> >> their
> >> > code". And then I thought about the rest of the codebase, about Jacques
> >> > Garrigue doing a walkthrough of the typechecker code, and each expert(s)
> >> > talking about the parts they know really well, and about how amazing it
> >> > would be if we had this resource on youtube. It would be the ultimate
> >> form
> >> > of documentation by the foremost experts on aspects OCaml, welcoming
> >> > programmers to contribute to the OCaml compiler in the easiest way
> >> possible.
> >> >
> >> > A step further would be if this was done on Twitch or some similar live
> >> > broadcasting platform, so people could actually ask live questions as
> >> the
> >> > session took place. The resulting video would be posted to youtube.
> >> >
> >> > What do you guys think?
> >> >
> >> > -Yotam
> >>
> >> I would watch that.
> >>
> >> MfG
> >>         Goswin
> >>
> >> --
> >> 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
> >>
> >
> >
> 
> -- 
> 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

Re: [Caml-list] Flambda/compiler walkthrough + modularity

[Yotam Barnoy]

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

On Mon, Mar 14, 2016 at 4:31 PM, Hendrik Boom <hendrik@topoi.pooq.com>
wrote:

>
> PR? I donn't know the acronym.
>
>
Pull Request -- github's term for a proposed commit to a git repository. It
supports a fairly detailed discussion mechanism on specific parts of the
code, which could enable building up of documentation through a
question-and-answer process.

-Yotam



> > (or others) would ask questions about functions I didn't understand, and
> > other people would step up and explain them. Eventually, there might be
> > some documentation and clarification to add to the code. This would
> require
> > tolerance of 'unhelpful' and question-based documentation PRs. There
> might
> > be some very basic questions in there. We could add a specific tag, so
> > these PRs aren't closed prematurely (they could take a while). Would that
> > be ok?
> >
> > -Yotam
> >
> >
> > > On Mon, Mar 14, 2016 at 11:36 AM, Goswin von Brederlow <
> goswin-v-b@web.de>
> > > wrote:
> > >
> > >> On Fri, Mar 11, 2016 at 12:04:17PM -0500, Yotam Barnoy wrote:
> > >> > While thinking about the best way to learn the new Flambda code in
> the
> > >> > minimal amount of time, I thought to myself, "wouldn't it be
> amazing to
> > >> > have Pierre Chambart and Mark Shinwell just do a video walkthrough
> of
> > >> their
> > >> > code". And then I thought about the rest of the codebase, about
> Jacques
> > >> > Garrigue doing a walkthrough of the typechecker code, and each
> expert(s)
> > >> > talking about the parts they know really well, and about how
> amazing it
> > >> > would be if we had this resource on youtube. It would be the
> ultimate
> > >> form
> > >> > of documentation by the foremost experts on aspects OCaml, welcoming
> > >> > programmers to contribute to the OCaml compiler in the easiest way
> > >> possible.
> > >> >
> > >> > A step further would be if this was done on Twitch or some similar
> live
> > >> > broadcasting platform, so people could actually ask live questions
> as
> > >> the
> > >> > session took place. The resulting video would be posted to youtube.
> > >> >
> > >> > What do you guys think?
> > >> >
> > >> > -Yotam
> > >>
> > >> I would watch that.
> > >>
> > >> MfG
> > >>         Goswin
> > >>
> > >> --
> > >> 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
> > >>
> > >
> > >
> >
> > --
> > 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
>
> --
> 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: 5087 bytes --]

Re: [Caml-list] Flambda/compiler walkthrough + modularity

[Junsong Li]

May I ask whether we have module owners in the core team? That is, are
modules assigned to people in the core team? Generally I think it is a
bad idea, but if it is done so, owners can review the crowd-sourced
comments in their module.

Or, can people voluntarily review the crowd-sourced comments in
modules that they know well?

Thanks. We eventually get to the comments. When I read the ocamldoc
source, I had a few Aha moments, but I had no idea what to do about
them: maybe I should write it down somewhere, but as it is not close
to the source, it will be obsoleted anyway. Why bother?

On Mon, Mar 14, 2016 at 6:51 AM, Yotam Barnoy <yotambarnoy@gmail.com> wrote:
> On Mon, Mar 14, 2016 at 8:30 AM, Gabriel Scherer <gabriel.scherer@gmail.com>
> wrote:
>>
>> A nice quality of in-code comments that a video session does not have is
>> locality: the explanations are closed to the explainees, so hopefully they
>> can evolve in synch. Another nice quality (shared with blog posts) is that
>> it can be proposed by third-parties and crowd-sourced with moderate
>> efficiency: you can help document the OCaml implementation by sending a
>> pull-request with comments on the parts you fought to understand.
>>
>> This has notably been done by Alain Frisch for the parsetree
>> representation during the 4.01 development phase, and recently (4.03
>> development cycle, GPR#310) in types.mli and typedtree.mli by Frédéric Bour,
>> Gabriel Radanne and Thomas Refis, with helpful feedback from Alain Frisch
>> and Jacques Garrigue.
>>
>> Anyone can help by submitting their own contribution to
>> documentation-as-comments.
>>
>
> This is absolutely true, and I'm extremely grateful to all who commented --
> the results are wonderful. The barriers to entry in this case, however, are
> knowledge, quality and effort. By contrast, Jacques Garrigue (sorry for
> picking on you Jacques) recording a session off the cuff on his laptop as he
> casually steps through the code in his editor (he wouldn't even need a
> webcam) and then uploading it to youtube would be a tremendous resource in
> and of itself.
>
> Another idea is that we develop a protocol for doing precisely this kind of
> evolutionary crowdsourced commenting, but take the initial barrier out of
> it.  Suppose that we allowed opening PRs on random files in the codebase. I
> (or others) would ask questions about functions I didn't understand, and
> other people would step up and explain them. Eventually, there might be some
> documentation and clarification to add to the code. This would require
> tolerance of 'unhelpful' and question-based documentation PRs. There might
> be some very basic questions in there. We could add a specific tag, so these
> PRs aren't closed prematurely (they could take a while). Would that be ok?
>
> -Yotam
>
>>
>> On Mon, Mar 14, 2016 at 11:36 AM, Goswin von Brederlow <goswin-v-b@web.de>
>> wrote:
>>>
>>> On Fri, Mar 11, 2016 at 12:04:17PM -0500, Yotam Barnoy wrote:
>>> > While thinking about the best way to learn the new Flambda code in the
>>> > minimal amount of time, I thought to myself, "wouldn't it be amazing to
>>> > have Pierre Chambart and Mark Shinwell just do a video walkthrough of
>>> > their
>>> > code". And then I thought about the rest of the codebase, about Jacques
>>> > Garrigue doing a walkthrough of the typechecker code, and each
>>> > expert(s)
>>> > talking about the parts they know really well, and about how amazing it
>>> > would be if we had this resource on youtube. It would be the ultimate
>>> > form
>>> > of documentation by the foremost experts on aspects OCaml, welcoming
>>> > programmers to contribute to the OCaml compiler in the easiest way
>>> > possible.
>>> >
>>> > A step further would be if this was done on Twitch or some similar live
>>> > broadcasting platform, so people could actually ask live questions as
>>> > the
>>> > session took place. The resulting video would be posted to youtube.
>>> >
>>> > What do you guys think?
>>> >
>>> > -Yotam
>>>
>>> I would watch that.
>>>
>>> MfG
>>>         Goswin
>>>
>>> --
>>> 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
>>
>>
>

Re: [Caml-list] Flambda/compiler walkthrough + modularity

[Gabriel Scherer]

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

On Mon, Mar 14, 2016 at 9:31 PM, Hendrik Boom <hendrik@topoi.pooq.com>
wrote:

> The main problem a technical writer faces in documenting someone
> else's software is to understand it.  Without that, he might produce
> elegant documentation that looks good but is utterly useless.
>

This is true, but note that this problem also happens when people
contribute code changes to the project. They start by constructing a local
understanding of what is happening, then use this knowledge to write a
patch. The patch may be a documentation patch, or a fix or a new feature,
and there is a risk in all cases. Currently people rather send code changes
only, so it's good to remind that they can also document their assumption
in passing (or just send documentation patches); a review will be needed
anyway.

I'm not assuming a separation of role between "development" and
"documentation" in my remark above. I never had the luck of working with
technical authors dedicated mostly to writing documentation, so I cannot
comment on how people with such a profile would best contribute -- but they
should definitely get in touch to sort it out.

(Sorry about the acronym-speak. PR is actually a loaded acronym for the
OCaml project right now, as it may denote either a "Pull Request" on the
github interface for code contributions, or a "Problem Report" on the
Mantis bugtracker. One can be explicit and say GPR and MPR. It is also
possible to send patches on the bugtracker, so here I should just have said
"patches".)

On Mon, Mar 14, 2016 at 10:05 PM, Junsong Li <ljs.darkfish@gmail.com> wrote:

> May I ask whether we have module owners in the core team? That is, are
> modules assigned to people in the core team? Generally I think it is a
> bad idea, but if it is done so, owners can review the crowd-sourced
> comments in their module.
>

Some regions of the codebase have a well-defined maintainer (typing ->
Jacques Garrigue, pattern-matching -> Luc Maranget, backend -> Xavier
Leroy, garbage collector -> Damien Doligez), and some people are experts on
more local or cross-cutting aspects. As far as I know, there is no formal
ownership structure, but people triaging bugs or change proposals will
usually know who to ask before making decisions. You don't need to know in
advance who would be the best reviewer to send a patch.


> Or, can people voluntarily review the crowd-sourced comments in modules
> that they know well?
>

Yes, and this is encouraged. More generally, people should feel free to
look at the bugreports and try to propose a fix (whether they "know well"
the affected part of the codebase or not), and to look at the proposed
patches and review them -- which means commenting on everything that feel
strange or that you do not understand in the patch.

On Mon, Mar 14, 2016 at 10:05 PM, Junsong Li <ljs.darkfish@gmail.com> wrote:

> May I ask whether we have module owners in the core team? That is, are
> modules assigned to people in the core team? Generally I think it is a
> bad idea, but if it is done so, owners can review the crowd-sourced
> comments in their module.
>
> Or, can people voluntarily review the crowd-sourced comments in
> modules that they know well?
>
> Thanks. We eventually get to the comments. When I read the ocamldoc
> source, I had a few Aha moments, but I had no idea what to do about
> them: maybe I should write it down somewhere, but as it is not close
> to the source, it will be obsoleted anyway. Why bother?
>
> On Mon, Mar 14, 2016 at 6:51 AM, Yotam Barnoy <yotambarnoy@gmail.com>
> wrote:
> > On Mon, Mar 14, 2016 at 8:30 AM, Gabriel Scherer <
> gabriel.scherer@gmail.com>
> > wrote:
> >>
> >> A nice quality of in-code comments that a video session does not have is
> >> locality: the explanations are closed to the explainees, so hopefully
> they
> >> can evolve in synch. Another nice quality (shared with blog posts) is
> that
> >> it can be proposed by third-parties and crowd-sourced with moderate
> >> efficiency: you can help document the OCaml implementation by sending a
> >> pull-request with comments on the parts you fought to understand.
> >>
> >> This has notably been done by Alain Frisch for the parsetree
> >> representation during the 4.01 development phase, and recently (4.03
> >> development cycle, GPR#310) in types.mli and typedtree.mli by Frédéric
> Bour,
> >> Gabriel Radanne and Thomas Refis, with helpful feedback from Alain
> Frisch
> >> and Jacques Garrigue.
> >>
> >> Anyone can help by submitting their own contribution to
> >> documentation-as-comments.
> >>
> >
> > This is absolutely true, and I'm extremely grateful to all who commented
> --
> > the results are wonderful. The barriers to entry in this case, however,
> are
> > knowledge, quality and effort. By contrast, Jacques Garrigue (sorry for
> > picking on you Jacques) recording a session off the cuff on his laptop
> as he
> > casually steps through the code in his editor (he wouldn't even need a
> > webcam) and then uploading it to youtube would be a tremendous resource
> in
> > and of itself.
> >
> > Another idea is that we develop a protocol for doing precisely this kind
> of
> > evolutionary crowdsourced commenting, but take the initial barrier out of
> > it.  Suppose that we allowed opening PRs on random files in the
> codebase. I
> > (or others) would ask questions about functions I didn't understand, and
> > other people would step up and explain them. Eventually, there might be
> some
> > documentation and clarification to add to the code. This would require
> > tolerance of 'unhelpful' and question-based documentation PRs. There
> might
> > be some very basic questions in there. We could add a specific tag, so
> these
> > PRs aren't closed prematurely (they could take a while). Would that be
> ok?
> >
> > -Yotam
> >
> >>
> >> On Mon, Mar 14, 2016 at 11:36 AM, Goswin von Brederlow <
> goswin-v-b@web.de>
> >> wrote:
> >>>
> >>> On Fri, Mar 11, 2016 at 12:04:17PM -0500, Yotam Barnoy wrote:
> >>> > While thinking about the best way to learn the new Flambda code in
> the
> >>> > minimal amount of time, I thought to myself, "wouldn't it be amazing
> to
> >>> > have Pierre Chambart and Mark Shinwell just do a video walkthrough of
> >>> > their
> >>> > code". And then I thought about the rest of the codebase, about
> Jacques
> >>> > Garrigue doing a walkthrough of the typechecker code, and each
> >>> > expert(s)
> >>> > talking about the parts they know really well, and about how amazing
> it
> >>> > would be if we had this resource on youtube. It would be the ultimate
> >>> > form
> >>> > of documentation by the foremost experts on aspects OCaml, welcoming
> >>> > programmers to contribute to the OCaml compiler in the easiest way
> >>> > possible.
> >>> >
> >>> > A step further would be if this was done on Twitch or some similar
> live
> >>> > broadcasting platform, so people could actually ask live questions as
> >>> > the
> >>> > session took place. The resulting video would be posted to youtube.
> >>> >
> >>> > What do you guys think?
> >>> >
> >>> > -Yotam
> >>>
> >>> I would watch that.
> >>>
> >>> MfG
> >>>         Goswin
> >>>
> >>> --
> >>> 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: 9914 bytes --]

Re: [Caml-list] Flambda/compiler walkthrough + modularity

[Junsong Li]

> Some regions of the codebase have a well-defined maintainer (typing ->
> Jacques Garrigue, pattern-matching -> Luc Maranget, backend -> Xavier Leroy,
> garbage collector -> Damien Doligez), and some people are experts on more
> local or cross-cutting aspects. As far as I know, there is no formal
> ownership structure, but people triaging bugs or change proposals will
> usually know who to ask before making decisions. You don't need to know in
> advance who would be the best reviewer to send a patch.
Oh, Thank you. It is good to know.

> Yes, and this is encouraged. More generally, people should feel free to look
> at the bugreports and try to propose a fix (whether they "know well" the
> affected part of the codebase or not), and to look at the proposed patches
> and review them -- which means commenting on everything that feel strange or
> that you do not understand in the patch.
Thanks.

Re: [Caml-list] <DKIM> Re: Flambda/compiler walkthrough + modularity

[Pierre Chambart]

Sorry for being that late in the discussion, but I like the idea. Let's
try something:

Ask questions about flambda on the (currently empty) PR:
https://github.com/ocaml/ocaml/pull/517
and I'll try to answer as comment commits.
-- 
Pierre