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 <[email protected]>
> ---
> 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 <[email protected]>
>
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 <[email protected]>
