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]> Reviewed-by: E Shattow <[email protected]> -- Changes for v2: - small wording changes to help non-native English speakers - add R-b Link to v1: https://patch.msgid.link/[email protected] --- Signed-off-by: Ralph Siemsen <[email protected]> --- To: [email protected] Cc: Tom Rini <[email protected]> Cc: Quentin Schulz <[email protected]> Cc: Ralph Siemsen <[email protected]> Cc: Neil Armstrong <[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..92bb2e203b8 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 are more easily accommodated. + +* 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 summary, 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: d1d45c926a571fb6c1e6d7105c280833646915ea change-id: 20261028-doc-sending-patches-d3a464feff98 Best regards, -- Ralph Siemsen <[email protected]>
