[PATCH] doc: develop/sending_patches: add tips for series

[PATCH] doc: develop/sending_patches: add tips for series

[Ralph Siemsen]

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>
---
 doc/develop/sending_patches.rst | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst
index b4f82eb18e1..b6c2a865928 100644
--- a/doc/develop/sending_patches.rst
+++ b/doc/develop/sending_patches.rst
@@ -184,6 +184,38 @@ 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 can be "squeezed in" more easily
+
+* tools like ``b4`` and ``patman`` will collect reviewers for each patch,
+  but then send the entire series to all reviewers found. This is not ideal
+  since it floods maintainers with patches they might not care about.
+
+A better approach is to break up a large series 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.
+
+Of course there are sometimes cases where a large patch series is okay:
+
+* when the changes are all in a specific area: for example when fixing a bug
+  in a driver, but also doing some refactoring or cleanup in the same code
+
+* when there are unavoidable dependencies between patches: keeping them
+  together avoids having to explain how multiple series are dependent
+
+In a nutshell, the goal should be to break up changes into smaller pieces,
+so the change can be more easily understood by reviewers. Combining multiple
+patches into a series makes sense as a way of grouping related changes, but
+if this results in a very large number of reviewers (eg. 25 or more) then
+the series should probably be split into smaller sub pieces.
+
 Attributing Code, Copyrights, Signing
 -------------------------------------
 

---
base-commit: 03e45557e1f38a39a0c80fe30483130ff376cf92
change-id: 20261028-doc-sending-patches-d3a464feff98

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

Re: [PATCH] doc: develop/sending_patches: add tips for series

[E Shattow]

Hi Ralph,

On 10/28/26 12:13, 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>
> ---
>  doc/develop/sending_patches.rst | 32 ++++++++++++++++++++++++++++++++
>  1 file changed, 32 insertions(+)
> 
> diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst
> index b4f82eb18e1..b6c2a865928 100644
> --- a/doc/develop/sending_patches.rst
> +++ b/doc/develop/sending_patches.rst
> @@ -184,6 +184,38 @@ 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 can be "squeezed in" more easily
> +
> +* tools like ``b4`` and ``patman`` will collect reviewers for each patch,
> +  but then send the entire series to all reviewers found. This is not ideal
> +  since it floods maintainers with patches they might not care about.
> +
> +A better approach is to break up a large series 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.
> +
> +Of course there are sometimes cases where a large patch series is okay:
> +
> +* when the changes are all in a specific area: for example when fixing a bug
> +  in a driver, but also doing some refactoring or cleanup in the same code
> +
> +* when there are unavoidable dependencies between patches: keeping them
> +  together avoids having to explain how multiple series are dependent
> +
> +In a nutshell, the goal should be to break up changes into smaller pieces,
> +so the change can be more easily understood by reviewers. Combining multiple
> +patches into a series makes sense as a way of grouping related changes, but
> +if this results in a very large number of reviewers (eg. 25 or more) then
> +the series should probably be split into smaller sub pieces.
> +
>  Attributing Code, Copyrights, Signing
>  -------------------------------------
>  
> 
> ---
> base-commit: 03e45557e1f38a39a0c80fe30483130ff376cf92
> change-id: 20261028-doc-sending-patches-d3a464feff98
> 
> Best regards,
> --  
> Ralph Siemsen <ralph.siemsen@linaro.org>
> 

I would substitute "nutshell" and "squeezed in" with something less
likely to confuse non-native English language contributors; ("In
summary, the goal...") ("reviews of a focused feature or concepts
supporting one idea is less demanding of a busy maintainer than a
collection of many smaller unrelated changes with no common idea").

with that, however you want to proceed it is already an improvement to
have the question illustrated of "what should I think about when
organizing a patch set?"

Reviewed-by: E Shattow <e@freeshell.de>

Re: [PATCH] doc: develop/sending_patches: add tips for series

[Ralph Siemsen]

On Wed, Oct 28, 2026 at 03:50:04PM -0700, E Shattow wrote:
>
>I would substitute "nutshell" and "squeezed in" with something less
>likely to confuse non-native English language contributors; ("In
>summary, the goal...") ("reviews of a focused feature or concepts
>supporting one idea is less demanding of a busy maintainer than a
>collection of many smaller unrelated changes with no common idea").

Thanks, I have adjusted the wording slightly. I'll give it another few 
days to see if anyone else has feedback.

Cheers,
Ralph