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

[E Shattow <e@freeshell.de>]

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>