Re: [docs] [PATCH 2/3] contributor-guide: add section about why we use mailing lists

[Richard Purdie <richard.purdie@linuxfoundation.org>]

On Wed, 2023-08-09 at 17:58 +0200, Frédéric Martinsons wrote:
> On Wed, 9 Aug 2023 at 16:25, Michael Opdenacker via
> lists.yoctoproject.org
> <michael.opdenacker=bootlin.com@lists.yoctoproject.org> wrote:
> 
> > +One significant factor is that we value peer review. When a change
> > is proposed
> > +to many of the core pieces of the project, it helps to have many
> > eyes of review
> > +go over them. Whilst there is ultimately one maintainer who needs
> > to make the
> > +final call on accepting or rejecting a patch, the review is made
> > by many eyes
> > +and the exact people reviewing it are likely unknown to the
> > maintainer. It is
> > +often the surprise reviewer that catches the most interesting
> > issues!
> > +
> > +This is in contrast to the "GitHub" style workflow where either
> > just a
> > +maintainer makes that review, or review is specifically requested
> > from
> > +nominated people. We believe there is significant value added to
> > the codebase
> > +by this peer review and that moving away from mailing lists would
> > be to the
> > +detriment of our code.
> > 
> 
> 
> For notifications, I don't see why the web flow would not allow to
> send notifications for changes to a mailing list (I think it can also
> be made per user profile to receive notifications for a whole
> project, an issue, a particular project ... etc)

You can make a web interface send notices to an email list, sure, that
isn't hard. Someone then replies giving feedback on the mailing list to
the patch. What happens to that feedback from the web point of view?
This "next step" is where the challenge is.

Patchwork is an attempt to make that match up and it basically shows
how hard this is to get right and pair the worlds up like that.
>  
> > +We also need to acknowledge that many of our developers are used
> > to this
> > +mailing list workflow and have worked with it for years, with
> > tools and
> > +processes built around it. Changing away from this would result in
> > a loss
> > +of key people from the project, which would again be to its
> > detriment.
> 
> I'd like to know some of these flow that are plugged on mail, can we
> insert some examples in the documentation ?

You mean document how mailing list patch work flow works?

> > +The projects are acutely aware that potential new contributors
> > find the
> > +mailing list approach off-putting and would prefer a point-and-
> > click web GUI.
> > 
> 
> 
> I find the term "point-and-click" a little patronizing,
> github/gitlab/others web tools
> are not just point-and-click machine but highly customizable tool
> aims at smoothen the developer work (in term of tracking, viewing
> diff, forking) and to provide enhanced user experience.

I agree we should tweak the wording.

>  
> > +Since we don’t believe that can work for us, the project is aiming
> > to ensure
> > +`patchwork <https://patchwork.yoctoproject.org/>` is available to
> > help track
> > +patch status and also looking at how tooling can provide more
> > feedback to users
> > +about patch status. We are looking at tools such as ``patchtest``
> > to
> > +test user contributions before they hit the mailing lists and also
> > at better
> > +documenting how to use such workflows since we recognise that
> > whilst this was
> > +common knowledge a decade ago, it might not be as familiar now.
> > 
> 
> 
> I didn't know patchtest, I'll look at it. I think a big improvement
> (at least for me) in the review
> process would be to some kind of colorized webview of a patch towards
> the target branch.

If you make a pull request from the contrib repos, you can see
colorized diffs using the web interfaces. You can also see that locally
with git itself or tools like gitk too. I do use both the cgit
interface and gitk commands at different times.

> Sorry, but , unless I miss some cool feature of my gmail client, I
> find that view (screenshot join) far more readable that raw diff by
> mail, e.g:

It does depend upon what you're used to. Personally, I can hand edit or
even hand write diff files :/. I'm not saying that is a good idea or a
good thing but it is what it is.

Cheers,

Richard