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]>
