All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH v4 0/2] doc: tips for submitting patch series
@ 2026-11-12 21:55 Ralph Siemsen
  2026-11-12 21:55 ` [PATCH v4 1/2] doc: develop/sending_patches: add tips for series Ralph Siemsen
  2026-11-12 21:55 ` [PATCH v4 2/2] doc: CONTRIBUTE: minor spelling and link Ralph Siemsen
  0 siblings, 2 replies; 7+ messages in thread
From: Ralph Siemsen @ 2026-11-12 21:55 UTC (permalink / raw)
  To: u-boot; +Cc: Tom Rini, Quentin Schulz, Neil Armstrong, Ralph Siemsen,
	E Shattow

--
Changes in v4:
- add second patch with minor update to CONTRIBUTE.rst

---
Ralph Siemsen (2):
      doc: develop/sending_patches: add tips for series
      doc: CONTRIBUTE: minor spelling and link

 doc/CONTRIBUTE.rst              |  4 +++-
 doc/develop/sending_patches.rst | 25 +++++++++++++++++++++++++
 2 files changed, 28 insertions(+), 1 deletion(-)
---
base-commit: a38a1d2736eed7978df10f513a5f6df4075b2277
change-id: 20261028-doc-sending-patches-d3a464feff98

Best regards,
--  
Ralph Siemsen <ralph.siemsen@linaro.org>


^ permalink raw reply	[flat|nested] 7+ messages in thread

* [PATCH v4 1/2] doc: develop/sending_patches: add tips for series
  2026-11-12 21:55 [PATCH v4 0/2] doc: tips for submitting patch series Ralph Siemsen
@ 2026-11-12 21:55 ` Ralph Siemsen
  2026-11-12 23:19   ` E Shattow
  2026-11-12 21:55 ` [PATCH v4 2/2] doc: CONTRIBUTE: minor spelling and link Ralph Siemsen
  1 sibling, 1 reply; 7+ messages in thread
From: Ralph Siemsen @ 2026-11-12 21:55 UTC (permalink / raw)
  To: u-boot; +Cc: Tom Rini, Quentin Schulz, Neil Armstrong, Ralph Siemsen,
	E Shattow

Related patches can be grouped into a "patch series". Add some tips on
how to decide how much belongs into a "patch series".

Signed-off-by: Ralph Siemsen <ralph.siemsen@linaro.org>
Reviewed-by: E Shattow <e@freeshell.de>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
--
Changes for v4:
- spelling fixes
- add R-b
- Line to v3: https://patch.msgid.link/20261106-doc-sending-patches-v3-1-86fa7d158cc2@linaro.org

Changes for v3:
- explicitly mention keeping bug fixes separate from other changes
- focus on "keep it small" rather than the exceptions to that rule
- Link to v2: https://patch.msgid.link/20261104-doc-sending-patches-v2-1-c0a90ff6c049@linaro.org

Changes for v2:
- small wording changes to help non-native English speakers
- add R-b

Link to v1:
https://patch.msgid.link/20261028-doc-sending-patches-v1-1-66b0f1b276de@linaro.org
---
 doc/develop/sending_patches.rst | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst
index 99581dc0ba0..dd06d4a8968 100644
--- a/doc/develop/sending_patches.rst
+++ b/doc/develop/sending_patches.rst
@@ -184,6 +184,31 @@ General Patch Submission Rules
   cases, you did something wrong if your patch exceeds this limit. Think again
   if you should not split it into separate logical parts.
 
+Tips for creating patch series
+------------------------------
+
+A series of related patches can be sent as a "patch series", as described
+above. Individual patches should be small and self-contained. Likewise,
+this also applies to each "patch series". Keep the following in mind:
+
+* large series are harder to review. Maintainers are busy and may postpone
+  large reviews, whereas smaller reviews are more easily accommodated.
+
+* bug fixes should not be part of a larger series, so that the fixes can
+  get reviewed and merged quickly.
+
+* tools like ``b4`` and ``patman`` send the entire patch series to all
+  reviewers, even though individual reviews may only care about some parts.
+  Filtering out the relevant parts takes time away from actual reviews.
+
+Therefore large series should be broken into smaller sub-series, for example by
+subsystem (clock, pinctrl, reset, etc.). This allows better targeting of only
+the relevant reviewers for each sub-series. Finding the right granularity can
+be difficult, but when in doubt, aim for smaller changes.
+
+Overall, the goal is to make changes easily understood by reviewers, as well
+as the next person who works on the code.
+
 Attributing Code, Copyrights, Signing
 -------------------------------------
 

-- 
2.55.0


^ permalink raw reply related	[flat|nested] 7+ messages in thread

* [PATCH v4 2/2] doc: CONTRIBUTE: minor spelling and link
  2026-11-12 21:55 [PATCH v4 0/2] doc: tips for submitting patch series Ralph Siemsen
  2026-11-12 21:55 ` [PATCH v4 1/2] doc: develop/sending_patches: add tips for series Ralph Siemsen
@ 2026-11-12 21:55 ` Ralph Siemsen
  2026-11-13 13:42   ` Quentin Schulz
  1 sibling, 1 reply; 7+ messages in thread
From: Ralph Siemsen @ 2026-11-12 21:55 UTC (permalink / raw)
  To: u-boot; +Cc: Tom Rini, Quentin Schulz, Neil Armstrong, Ralph Siemsen

Two minor fixes:
- standardize the spelling of "self-contained" to include the dash.
- add a link to develop/sending_patches.rst

Signed-off-by: Ralph Siemsen <ralph.siemsen@linaro.org>
---
 doc/CONTRIBUTE.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/CONTRIBUTE.rst b/doc/CONTRIBUTE.rst
index e38b1875a70..956cf546fec 100644
--- a/doc/CONTRIBUTE.rst
+++ b/doc/CONTRIBUTE.rst
@@ -59,7 +59,7 @@ Patch Series
 
 Patch series for a specific subject are welcome but they should be constrained
 to a single topic with a cover letter outlining the intention of the series.
-Each patch within the series should cover a single change, be self contained,
+Each patch within the series should cover a single change, be self-contained,
 not break the build or cause a regression.
 
 Generally bug fixes for existing bugs should be at the beginning of the
@@ -70,6 +70,8 @@ to review previous versions of the series and incorporate all the review
 feedback before sending a new version. A week between larger patch sets is
 considered as reasonable amount of time.
 
+Additional tips can be found in :doc:`develop/sending_patches`.
+
 Development Branches
 --------------------
 

-- 
2.55.0


^ permalink raw reply related	[flat|nested] 7+ messages in thread

* Re: [PATCH v4 1/2] doc: develop/sending_patches: add tips for series
  2026-11-12 21:55 ` [PATCH v4 1/2] doc: develop/sending_patches: add tips for series Ralph Siemsen
@ 2026-11-12 23:19   ` E Shattow
  2026-11-13 13:42     ` Quentin Schulz
  2026-11-17 19:31     ` Ralph Siemsen
  0 siblings, 2 replies; 7+ messages in thread
From: E Shattow @ 2026-11-12 23:19 UTC (permalink / raw)
  To: Ralph Siemsen, u-boot; +Cc: Tom Rini, Quentin Schulz, Neil Armstrong



On 11/12/26 13:55, Ralph Siemsen wrote:
> Related patches can be grouped into a "patch series". Add some tips on
> how to decide how much belongs into a "patch series".
> 
> Signed-off-by: Ralph Siemsen <ralph.siemsen@linaro.org>
> Reviewed-by: E Shattow <e@freeshell.de>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
> --
> Changes for v4:
> - spelling fixes
> - add R-b
> - Line to v3: https://patch.msgid.link/20261106-doc-sending-patches-v3-1-86fa7d158cc2@linaro.org
> 
> Changes for v3:
> - explicitly mention keeping bug fixes separate from other changes
> - focus on "keep it small" rather than the exceptions to that rule
> - Link to v2: https://patch.msgid.link/20261104-doc-sending-patches-v2-1-c0a90ff6c049@linaro.org
> 
> Changes for v2:
> - small wording changes to help non-native English speakers
> - add R-b
> 
> Link to v1:
> https://patch.msgid.link/20261028-doc-sending-patches-v1-1-66b0f1b276de@linaro.org
> ---
>  doc/develop/sending_patches.rst | 25 +++++++++++++++++++++++++
>  1 file changed, 25 insertions(+)
> 
> diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst
> index 99581dc0ba0..dd06d4a8968 100644
> --- a/doc/develop/sending_patches.rst
> +++ b/doc/develop/sending_patches.rst
> @@ -184,6 +184,31 @@ General Patch Submission Rules
>    cases, you did something wrong if your patch exceeds this limit. Think again
>    if you should not split it into separate logical parts.
>  
> +Tips for creating patch series
> +------------------------------
> +
> +A series of related patches can be sent as a "patch series", as described
> +above. Individual patches should be small and self-contained. Likewise,
> +this also applies to each "patch series". Keep the following in mind:
> +
> +* large series are harder to review. Maintainers are busy and may postpone

This reads a bit awkwardly. Maybe "A large series is harder to review"
or "large series patches are harder to review", depending on what the
meaning is you are wanting to convey.

Either seems to me like injecting your opinion about what is easy or
difficult to review which does not align with my view of this that the
difficulty in reviewing a patch series is proportional to the discipline
in focus the author has for presenting their idea and developing it to a
meaningful change with the assistance of code review;  if it will
require a great deal of involvement then don't expect to just dump your
code off on the list and have it be merged because you gave this "gift"
of 100+ small patches in a series, or even a single patch large-or-small
that is several disjointed ideas or bug fixes.

> +  large reviews, whereas smaller reviews are more easily accommodated.
> +
> +* bug fixes should not be part of a larger series, so that the fixes can
> +  get reviewed and merged quickly.

Nothing happens "quickly". The point of bug fixes being independent is
so they can be reviewed and verified independently from unrelated
changes. Quickness is not the driver of getting merged or not merged, or
it should not be.

> +
> +* tools like ``b4`` and ``patman`` send the entire patch series to all

Do correct me if I am mistaken: for consistency I think we are
recommending people use b4 and patman, and not tools similar to these.

> +  reviewers, even though individual reviews may only care about some parts.
> +  Filtering out the relevant parts takes time away from actual reviews.
> +

What is an "actual review" ? That sounds so strange.

> +Therefore large series should be broken into smaller sub-series, for example by
> +subsystem (clock, pinctrl, reset, etc.). This allows better targeting of only
> +the relevant reviewers for each sub-series. Finding the right granularity can
> +be difficult, but when in doubt, aim for smaller changes.
> +
> +Overall, the goal is to make changes easily understood by reviewers, as well
> +as the next person who works on the code.
> +
>  Attributing Code, Copyrights, Signing
>  -------------------------------------
>  
> 

Drop my R-by tag, thanks. -E

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH v4 2/2] doc: CONTRIBUTE: minor spelling and link
  2026-11-12 21:55 ` [PATCH v4 2/2] doc: CONTRIBUTE: minor spelling and link Ralph Siemsen
@ 2026-11-13 13:42   ` Quentin Schulz
  0 siblings, 0 replies; 7+ messages in thread
From: Quentin Schulz @ 2026-11-13 13:42 UTC (permalink / raw)
  To: Ralph Siemsen, u-boot; +Cc: Tom Rini, Neil Armstrong

Hi Ralph,

On 11/12/26 10:55 PM, Ralph Siemsen wrote:
> Two minor fixes:
> - standardize the spelling of "self-contained" to include the dash.
> - add a link to develop/sending_patches.rst
> 

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH v4 1/2] doc: develop/sending_patches: add tips for series
  2026-11-12 23:19   ` E Shattow
@ 2026-11-13 13:42     ` Quentin Schulz
  2026-11-17 19:31     ` Ralph Siemsen
  1 sibling, 0 replies; 7+ messages in thread
From: Quentin Schulz @ 2026-11-13 13:42 UTC (permalink / raw)
  To: E Shattow, Ralph Siemsen, u-boot; +Cc: Tom Rini, Neil Armstrong

Hi E, Ralph,

On 11/13/26 12:19 AM, E Shattow wrote:
> 
> 
> On 11/12/26 13:55, Ralph Siemsen wrote:
>> Related patches can be grouped into a "patch series". Add some tips on
>> how to decide how much belongs into a "patch series".
>>
>> Signed-off-by: Ralph Siemsen <ralph.siemsen@linaro.org>
>> Reviewed-by: E Shattow <e@freeshell.de>
>> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
>> --
>> Changes for v4:
>> - spelling fixes
>> - add R-b
>> - Line to v3: https://patch.msgid.link/20261106-doc-sending-patches-v3-1-86fa7d158cc2@linaro.org
>>
>> Changes for v3:
>> - explicitly mention keeping bug fixes separate from other changes
>> - focus on "keep it small" rather than the exceptions to that rule
>> - Link to v2: https://patch.msgid.link/20261104-doc-sending-patches-v2-1-c0a90ff6c049@linaro.org
>>
>> Changes for v2:
>> - small wording changes to help non-native English speakers
>> - add R-b
>>
>> Link to v1:
>> https://patch.msgid.link/20261028-doc-sending-patches-v1-1-66b0f1b276de@linaro.org
>> ---
>>   doc/develop/sending_patches.rst | 25 +++++++++++++++++++++++++
>>   1 file changed, 25 insertions(+)
>>
>> diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst
>> index 99581dc0ba0..dd06d4a8968 100644
>> --- a/doc/develop/sending_patches.rst
>> +++ b/doc/develop/sending_patches.rst
>> @@ -184,6 +184,31 @@ General Patch Submission Rules
>>     cases, you did something wrong if your patch exceeds this limit. Think again
>>     if you should not split it into separate logical parts.
>>   
>> +Tips for creating patch series
>> +------------------------------
>> +
>> +A series of related patches can be sent as a "patch series", as described
>> +above. Individual patches should be small and self-contained. Likewise,
>> +this also applies to each "patch series". Keep the following in mind:
>> +
>> +* large series are harder to review. Maintainers are busy and may postpone
> 
> This reads a bit awkwardly. Maybe "A large series is harder to review"
> or "large series patches are harder to review", depending on what the
> meaning is you are wanting to convey.
> 

Did you mean to ask for clarification on whether the "large" part 
applies to the series itself (the number of patches in it) or to the 
individual patches in the series (multiple large patches in a singular 
series)? I think it applies to both.

> Either seems to me like injecting your opinion about what is easy or
> difficult to review which does not align with my view of this that the

OK, what about

s/are harder to review/typically take longer to review/

Would this be better wording?

> difficulty in reviewing a patch series is proportional to the discipline
> in focus the author has for presenting their idea and developing it to a
> meaningful change with the assistance of code review;  if it will

How does one know their discipline is up to (y)our standards?

The point is not to give a recipe for patch series you have to 
absolutely follow, because no such thing exists. Here we're attempting 
to give something that is at least quantifiable as that's much easier 
for people to gauge than quality. Is it perfect? No, but I think it's 
still some improvement over what we have today.

People do reviews differently, custodians have different (often implied, 
sometimes not consistent over time) rules for code under their 
custodianship, we won't find a "rule" that makes everybody happy.

> require a great deal of involvement then don't expect to just dump your
> code off on the list and have it be merged because you gave this "gift"
> of 100+ small patches in a series, or even a single patch large-or-small
> that is several disjointed ideas or bug fixes.
> 

Single large patch is covered by:

"""
Individual patches should be small
"""

Single small-with-disjointed-ideas patch is covered by:

"""
and self-contained.
"""

As well as

"""
Patches should always contain exactly one complete logical change
"""

in the General Patch Submission Rules section just above the one Ralph 
is adding here.

The 100+ small patches in a series is covered by the second sentence in:

"""
Individual patches should be small and self-contained. Likewise, this 
also applies to each "patch series".
"""

What are you suggesting as changes to make this clearer?

>> +  large reviews, whereas smaller reviews are more easily accommodated.
>> +
>> +* bug fixes should not be part of a larger series, so that the fixes can
>> +  get reviewed and merged quickly.
> 
> Nothing happens "quickly". The point of bug fixes being independent is
> so they can be reviewed and verified independently from unrelated
> changes. Quickness is not the driver of getting merged or not merged, or
> it should not be.
> 

Fixes should have higher importance than adding features. Fixes can 
(with some exceptions) be merged at any time in the development cycle, 
whereas new features, new drivers, etc..., can only be merged during the 
merge window, 3-week-long every quarter.

Contributors care about their thing being merged quickly so they don't 
have to send new versions or make sure it didn't get forgotten.

>> +
>> +* tools like ``b4`` and ``patman`` send the entire patch series to all
> 
> Do correct me if I am mistaken: for consistency I think we are
> recommending people use b4 and patman, and not tools similar to these.
> 

You can use git-send-email, or whatever else tool you want to use. Send 
us patches we can apply with git am and that aren't attached to the 
mail, the rest we don't care. We recommend b4 because it's much more 
accessible to new (and long-time, I use it for every contribution) 
contributors. We recommend(ed?) patman because this is what some 
contributors/custodians are (were?) using before b4 came to life a few 
years back.

>> +  reviewers, even though individual reviews may only care about some parts.
>> +  Filtering out the relevant parts takes time away from actual reviews.
>> +
> 
> What is an "actual review" ? That sounds so strange.
> 

I think the point was that merely looking at a series could count as 
reviewing, while looking at individual patches in depth also are, but to 
a different degree. I think what Ralph meant to say is that the second 
part is an "actual" review in the sense that that's what the contributor 
will see once they receive feedback on it whereas the filtering isn't 
something visible to external people. But I don't think it brings much 
to the sentence, so if Ralph agrees we can just remove it and avoid 
confusion.

Cheers,
Quentin

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH v4 1/2] doc: develop/sending_patches: add tips for series
  2026-11-12 23:19   ` E Shattow
  2026-11-13 13:42     ` Quentin Schulz
@ 2026-11-17 19:31     ` Ralph Siemsen
  1 sibling, 0 replies; 7+ messages in thread
From: Ralph Siemsen @ 2026-11-17 19:31 UTC (permalink / raw)
  To: E Shattow; +Cc: u-boot, Tom Rini, Quentin Schulz, Neil Armstrong

On Thu, Nov 12, 2026 at 03:19:18PM -0800, E Shattow wrote:
>On 11/12/26 13:55, Ralph Siemsen wrote:
>> +
>> +A series of related patches can be sent as a "patch series", as described
>> +above. Individual patches should be small and self-contained. Likewise,
>> +this also applies to each "patch series". Keep the following in mind:
>> +
>> +* large series are harder to review. Maintainers are busy and may postpone
>
>This reads a bit awkwardly. Maybe "A large series is harder to review"
>or "large series patches are harder to review", depending on what the
>meaning is you are wanting to convey.

I'll see if I can reword it more clearly. I was referring to series with 
a large number of patches. The existing document already talks about 
(individual) large patches.

>Either seems to me like injecting your opinion about what is easy or
>difficult to review which does not align with my view of this that the
>difficulty in reviewing a patch series is proportional to the discipline
>in focus the author has for presenting their idea and developing it to a
>meaningful change with the assistance of code review; 

Knowing how to present ideas clearly and develop them based on review 
feedback is something that must be learned. Some people are naturally 
good at it, but the rest of us appreciate all the guidance we can get.

>if it will
>require a great deal of involvement then don't expect to just dump your
>code off on the list and have it be merged because you gave this "gift"
>of 100+ small patches in a series, or even a single patch large-or-small
>that is several disjointed ideas or bug fixes.

How can we help an author to recognize that their code is going to 
require a great deal of involvement from the reviewer? Most submissions 
are made in good faith, with lots of effort on the author's part. The 
author cannot read the reviewer's mind, so we have to try to document 
expectations as best we can. That was my goal with this change.

>Nothing happens "quickly". The point of bug fixes being independent is
>so they can be reviewed and verified independently from unrelated
>changes. Quickness is not the driver of getting merged or not merged, or
>it should not be.

I'll reword it without "quickly". But I do think that certain bug fixes 
are more urgent, and should be handled "quickly". Such fixes should not 
be bundled into a series with other changes. Which seems pretty obvious, 
but still worth writing down.

>> +* tools like ``b4`` and ``patman`` send the entire patch series to
>
>Do correct me if I am mistaken: for consistency I think we are
>recommending people use b4 and patman, and not tools similar to these.

Indeed those two are recommended earlier in the document. I'll remove 
the ambiguous "like" and just write "The b4 and patman tools ..."

>> +  reviewers, even though individual reviews may only care about some 
>> parts.
>> +  Filtering out the relevant parts takes time away from actual reviews.
>> +
>What is an "actual review" ? That sounds so strange.

I meant "actually doing code review", as opposed time spent filtering 
out emails (parts of series) that are not of interest to the reviewer.

The tools collect reviewers for each patch in a series, but they send 
all patches to all reviewers. So if the series contains changes to 
driver A and B, each with their own maintainer, then both maintainers 
have to dig out the part they care about.

To avoid this, authors need to be aware of this when using the tools. 
One warning sign is a large list of auto-generated recipients, which 
usually indicates that change needs to be split up further.

>Drop my R-by tag, thanks. -E

Will do.

-R

^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2026-11-17 19:31 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-12 21:55 [PATCH v4 0/2] doc: tips for submitting patch series Ralph Siemsen
2026-11-12 21:55 ` [PATCH v4 1/2] doc: develop/sending_patches: add tips for series Ralph Siemsen
2026-11-12 23:19   ` E Shattow
2026-11-13 13:42     ` Quentin Schulz
2026-11-17 19:31     ` Ralph Siemsen
2026-11-12 21:55 ` [PATCH v4 2/2] doc: CONTRIBUTE: minor spelling and link Ralph Siemsen
2026-11-13 13:42   ` Quentin Schulz

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.