[PATCH net v2 0/3] docs: netdev: document more of our rules

[PATCH net v2 0/3] docs: netdev: document more of our rules

[Jakub Kicinski]

The patch series length limit and reverse xmas tree are not documented.
Add those, and a tl;dr section summarizing how we differ.

v2: improve the series length blurb (Andrew)

Jakub Kicinski (3):
  docs: netdev: document that patch series length limit
  docs: netdev: document reverse xmas tree
  docs: netdev: add a cheat sheet for the rules

 Documentation/process/maintainer-netdev.rst | 36 +++++++++++++++++++++
 1 file changed, 36 insertions(+)

-- 
2.36.1

[PATCH net v2 1/3] docs: netdev: document that patch series length limit

[Jakub Kicinski]

We had been asking people to avoid massive patch series but it does
not appear in the FAQ.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
 Documentation/process/maintainer-netdev.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst
index c456b5225d66..79a10d05031e 100644
--- a/Documentation/process/maintainer-netdev.rst
+++ b/Documentation/process/maintainer-netdev.rst
@@ -136,6 +136,20 @@ it to the maintainer to figure out what is the most recent and current
 version that should be applied. If there is any doubt, the maintainer
 will reply and ask what should be done.
 
+How do I divide my work into patches?
+-------------------------------------
+
+Put yourself in the shoes of the reviewer. Each patch is read separately
+and therefore should constitute a comprehensible step towards your stated
+goal.
+
+Avoid sending series longer than 15 patches. Larger series takes longer
+to review as reviewers will defer looking at it until they find a large
+chunk of time. A small series can be reviewed in a short time, so Maintainers
+just do it. As a result, a sequence of smaller series gets merged quicker and
+with better review coverage. Re-posting large series also increases the mailing
+list traffic.
+
 I made changes to only a few patches in a patch series should I resend only those changed?
 ------------------------------------------------------------------------------------------
 No, please resend the entire patch series and make sure you do number your
-- 
2.36.1

[PATCH net v2 2/3] docs: netdev: document reverse xmas tree

[Jakub Kicinski]

Similarly to the 15 patch rule the reverse xmas tree is not
documented.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
 Documentation/process/maintainer-netdev.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst
index 79a10d05031e..8a9dae7a0524 100644
--- a/Documentation/process/maintainer-netdev.rst
+++ b/Documentation/process/maintainer-netdev.rst
@@ -197,6 +197,19 @@ Is the comment style convention different for the networking content?
    * another line of text
    */
 
+What is "reverse xmas tree"?
+----------------------------
+
+Netdev has a convention for ordering local variables in functions.
+Order the variable declaration lines longest to shortest, e.g.::
+
+  struct scatterlist *sg;
+  struct sk_buff *skb;
+  int err, i;
+
+If there are dependencies between the variables preventing the ordering
+move the initialization out of line.
+
 I am working in existing code which uses non-standard formatting. Which formatting should I use?
 ------------------------------------------------------------------------------------------------
 Make your code follow the most recent guidelines, so that eventually all code
-- 
2.36.1

[PATCH net v2 3/3] docs: netdev: add a cheat sheet for the rules

[Jakub Kicinski]

Summarize the rules we see broken most often and which may
be less familiar to kernel devs who are used to working outside
of netdev.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
 Documentation/process/maintainer-netdev.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst
index 8a9dae7a0524..d14007081595 100644
--- a/Documentation/process/maintainer-netdev.rst
+++ b/Documentation/process/maintainer-netdev.rst
@@ -6,6 +6,15 @@
 netdev FAQ
 ==========
 
+tl;dr
+-----
+
+ - designate your patch to a tree - ``[PATCH net]`` or ``[PATCH net-next]``
+ - for fixes the ``Fixes:`` tag is required, regardless of the tree
+ - don't post large series (> 15 patches), break them up
+ - don't repost your patches within one 24h period
+ - reverse xmas tree
+
 What is netdev?
 ---------------
 It is a mailing list for all network-related Linux stuff.  This
-- 
2.36.1

Re: [PATCH net v2 1/3] docs: netdev: document that patch series length limit

[Andrew Lunn]

On Fri, Jul 01, 2022 at 08:12:07PM -0700, Jakub Kicinski wrote:
> We had been asking people to avoid massive patch series but it does
> not appear in the FAQ.
> 
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>

Reviewed-by: Andrew Lunn <andrew@lunn.ch>

    Andrew

Re: [PATCH net v2 2/3] docs: netdev: document reverse xmas tree

[Andrew Lunn]

On Fri, Jul 01, 2022 at 08:12:08PM -0700, Jakub Kicinski wrote:
> Similarly to the 15 patch rule the reverse xmas tree is not
> documented.
> 
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>

Reviewed-by: Andrew Lunn <andrew@lunn.ch>

    Andrew

Re: [PATCH net v2 3/3] docs: netdev: add a cheat sheet for the rules

[Andrew Lunn]

On Fri, Jul 01, 2022 at 08:12:09PM -0700, Jakub Kicinski wrote:
> Summarize the rules we see broken most often and which may
> be less familiar to kernel devs who are used to working outside
> of netdev.
> 
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>

Reviewed-by: Andrew Lunn <andrew@lunn.ch>

    Andrew

Re: [PATCH net v2 0/3] docs: netdev: document more of our rules

[patchwork-bot+netdevbpf]

Hello:

This series was applied to netdev/net.git (master)
by David S. Miller <davem@davemloft.net>:

On Fri,  1 Jul 2022 20:12:06 -0700 you wrote:
> The patch series length limit and reverse xmas tree are not documented.
> Add those, and a tl;dr section summarizing how we differ.
> 
> v2: improve the series length blurb (Andrew)
> 
> Jakub Kicinski (3):
>   docs: netdev: document that patch series length limit
>   docs: netdev: document reverse xmas tree
>   docs: netdev: add a cheat sheet for the rules
> 
> [...]

Here is the summary with links:
  - [net,v2,1/3] docs: netdev: document that patch series length limit
    https://git.kernel.org/netdev/net/c/02514a067fad
  - [net,v2,2/3] docs: netdev: document reverse xmas tree
    https://git.kernel.org/netdev/net/c/a24875641143
  - [net,v2,3/3] docs: netdev: add a cheat sheet for the rules
    https://git.kernel.org/netdev/net/c/5d407ca73892

You are awesome, thank you!
-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html