Re: [libgpiod][PATCH] README: provide more info in Contributing

[Bartosz Golaszewski <brgl@xxxxxxxx>]

On Tue, May 23, 2023 at 9:41 AM Bartosz Golaszewski <brgl@xxxxxxxx> wrote:
>
> On Tue, May 23, 2023 at 4:21 AM Kent Gibson <warthog618@xxxxxxxxx> wrote:
> >
> > On Mon, May 22, 2023 at 06:29:27PM +0200, Bartosz Golaszewski wrote:
> > > On Sat, May 20, 2023 at 5:12 AM Kent Gibson <warthog618@xxxxxxxxx> wrote:
> > > >
> > > > Add more detail to Contributing to make it easier for new users to
> > > > contribute.
> > > >
> > > > Signed-off-by: Kent Gibson <warthog618@xxxxxxxxx>
> > > > ---
> > > > I was tempted to add something on formatting with clang-format, but I'm
> > > > not 100% clear on the formatting policy myself.
> > > > Would be nice for that to be clarified.
> > > >
> > > >  README | 14 +++++++++++---
> > > >  1 file changed, 11 insertions(+), 3 deletions(-)
> > > >
> > > > diff --git a/README b/README
> > > > index b71739e..8e726fe 100644
> > > > --- a/README
> > > > +++ b/README
> > > > @@ -275,8 +275,16 @@ were selected and help2man is available in the system.
> > > >  CONTRIBUTING
> > > >  ------------
> > > >
> > > > -Contributions are welcome - please send patches and bug reports to
> > > > -linux-gpio@xxxxxxxxxxxxxxx (add the [libgpiod] prefix to the e-mail subject
> > > > -line) and stick to the linux kernel coding style when submitting new code.
> > > > +Contributions are welcome - please send questions, patches and bug reports
> > > > +to linux-gpio@xxxxxxxxxxxxxxx (add the [libgpiod] prefix to the e-mail
> > > > +subject line).  Note that the mailing list quietly drops HTML formatted
> > > > +e-mail, so be sure to send plain text[2].
> > > > +
> > > > +Code submissions should stick to the linux kernel coding style[3] and
> > > > +follow the kernel patch submission process[4] as applied to the libgpiod
> > > > +source tree.
> > > >
> > > >  [1] https://github.com/bats-core/bats-core
> > > > +[2] https://docs.kernel.org/process/email-clients.html
> > > > +[3] https://docs.kernel.org/process/coding-style.html
> > > > +[4] https://docs.kernel.org/process/submitting-patches.html
> > > > --
> > > > 2.40.1
> > > >
> > >
> > > Thanks for doing this. Maybe even add a link to the linux-gpio mailing
> > > list main page and archives? I sometimes get mail from people confused
> > > as to what the linux-gpio mailing list actually is.
> > >
> >
> > Fair point - will add something in v2.
> >
> > Anything to add on formatting?
> > I was going to mention clang-format, but IIRC you tweak that a bit where
> > the old way looks nicer.
>
> I used the kernel's .clang-format but in some places it resulted in
> worse readability.
>
> > FWIW I'd rather the clang-format was definitive, or if you can't get
> > what you want from clang directly, that any tweaking could be automated.
> > Essentially that there is some definitive format that can be applied by
> > a tool - I'd rather not be spending time musing over whitespace.
> >
>
> I agree. I'll revisit the kernel's format file and see if I can tweak it a bit.
>
> Until that's done let's leave it out of README though.
>
> Bart

Ah, I remember now why I hated the "official" kernel .clang-format
which the kernel doesn't even seem to use itself because this is an
example of what applying it results in:

-        static const GPIOSimLineName names[] = {
-                { .offset = 1, .name = "foo", },
-                { .offset = 2, .name = "bar", },
-                { .offset = 4, .name = "baz", },
-                { .offset = 5, .name = "xyz", },
-                { }
-        };
+        static const GPIOSimLineName names[] = { {
+                                                         .offset = 1,
+                                                         .name = "foo",
+                                                 },
+                                                 {
+                                                         .offset = 2,
+                                                         .name = "bar",
+                                                 },
+                                                 {
+                                                         .offset = 4,
+                                                         .name = "baz",
+                                                 },
+                                                 {
+                                                         .offset = 5,
+                                                         .name = "xyz",
+                                                 },
+                                                 {} };

Bart