Skip to contentSkip to conversation

README: provide more info in Contributing

PATCH Superseded Kent Gibson 2 participants 5 messages May 20, 2023 – May 23, 2023 GPIO

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 README: provide more info in Contributing

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

---
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(-)
README +11 -3
index b71739e..8e726fe 100644
@@ -275,8 +275,16 @@ were selected and help2man is available in the system.
 CONTRIBUTING
 ------------
 
-Contributions are welcome - please send patches and bug reports to
[email protected] (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 [email protected] (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
Signature · 1 line
2.40.1
#1 lore raw
Quoted 38 lines · Kent Gibson

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

---
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(-)
README +11 -4
index b71739e..8e726fe 100644
@@ -275,8 +275,16 @@ were selected and help2man is available in the system.
 CONTRIBUTING
 ------------
 
-Contributions are welcome - please send patches and bug reports to
[email protected] (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 [email protected] (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
--
Quoted 2 lines

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

#2 lore raw
Quoted 34 lines · Bartosz Golaszewski
Quoted 33 lines · Kent Gibson

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

---
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(-)
README +8 -3
index b71739e..8e726fe 100644
@@ -275,8 +275,16 @@ were selected and help2man is available in the system.
 CONTRIBUTING
 ------------
 
-Contributions are welcome - please send patches and bug reports to
[email protected] (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 [email protected] (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.
 
Quoted 12 lines
Quoted 7 lines
README +3 -1
 [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.

#3 lore raw
Quoted 49 lines · Kent Gibson
Quoted 34 lines · Bartosz Golaszewski
Quoted 33 lines · Kent Gibson

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

---
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(-)
README +8 -3
index b71739e..8e726fe 100644
@@ -275,8 +275,16 @@ were selected and help2man is available in the system.
 CONTRIBUTING
 ------------
 
-Contributions are welcome - please send patches and bug reports to
[email protected] (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 [email protected] (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.
 
Quoted 12 lines
Quoted 7 lines
README +3 -1
 [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.

Quoted 5 lines

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.

Quoted 5 lines

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

#4 lore raw
Quoted 66 lines · Bartosz Golaszewski
Quoted 49 lines · Kent Gibson
Quoted 34 lines · Bartosz Golaszewski
Quoted 33 lines · Kent Gibson

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

---
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(-)
README +8 -3
index b71739e..8e726fe 100644
@@ -275,8 +275,16 @@ were selected and help2man is available in the system.
 CONTRIBUTING
 ------------
 
-Contributions are welcome - please send patches and bug reports to
[email protected] (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 [email protected] (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.
 
Quoted 12 lines
Quoted 7 lines
README +3 -1
 [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.

Quoted 5 lines

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.

Quoted 5 lines

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.

Quoted 5 lines

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