[libgpiod] README: provide more info in Contributing

Add more detail to Contributing to make it easier for new users to
contribute.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
---
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(-)

On Sat, May 20, 2023 at 5:12 AM Kent Gibson <warthog618@gmail.com> wrote:
>
> Add more detail to Contributing to make it easier for new users to
> contribute.
>
> Signed-off-by: Kent Gibson <warthog618@gmail.com>
> ---
> 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@vger.kernel.org (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@vger.kernel.org (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.

Bart

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@gmail.com> wrote:
> >
> > Add more detail to Contributing to make it easier for new users to
> > contribute.
> >
> > Signed-off-by: Kent Gibson <warthog618@gmail.com>
> > ---
> > 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@vger.kernel.org (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@vger.kernel.org (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.
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.

Cheers,
Kent.

On Tue, May 23, 2023 at 4:21 AM Kent Gibson <warthog618@gmail.com> 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@gmail.com> wrote:
> > >
> > > Add more detail to Contributing to make it easier for new users to
> > > contribute.
> > >
> > > Signed-off-by: Kent Gibson <warthog618@gmail.com>
> > > ---
> > > 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@vger.kernel.org (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@vger.kernel.org (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

On Tue, May 23, 2023 at 9:41 AM Bartosz Golaszewski <brgl@bgdev.pl> wrote:
>
> On Tue, May 23, 2023 at 4:21 AM Kent Gibson <warthog618@gmail.com> 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@gmail.com> wrote:
> > > >
> > > > Add more detail to Contributing to make it easier for new users to
> > > > contribute.
> > > >
> > > > Signed-off-by: Kent Gibson <warthog618@gmail.com>
> > > > ---
> > > > 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@vger.kernel.org (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@vger.kernel.org (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