Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

docs: try to encourage (netdev?) reviewers

Add a section to netdev maintainer doc encouraging reviewers
to chime in on the mailing list.

The questions about "when is it okay to share feedback"
keep coming up (most recently at netconf) and the answer
is "pretty much always".

Extend the section of 7.AdvancedTopics.rst which deals
with reviews a little bit to add stuff we had been recommending
locally.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Reviewed-by: Florian Fainelli <florian.fainelli@broadcom.com>
Reviewed-by: Martin Habets <habetsm.xilinx@gmail.com>
Signed-off-by: David S. Miller <davem@davemloft.net>

authored by

Jakub Kicinski and committed by
David S. Miller
6e55b1cb 4d825faf

+33
+18
Documentation/process/7.AdvancedTopics.rst
··· 146 146 format the request as other developers expect, and will also check to be 147 147 sure that you have remembered to push those changes to the public server. 148 148 149 + .. _development_advancedtopics_reviews: 149 150 150 151 Reviewing patches 151 152 ----------------- ··· 168 167 get released in this path?" will always work better than stating "the 169 168 locking here is wrong." 170 169 170 + Another technique that is useful in case of a disagreement is to ask for others 171 + to chime in. If a discussion reaches a stalemate after a few exchanges, 172 + then call for opinions of other reviewers or maintainers. Often those in 173 + agreement with a reviewer remain silent unless called upon. 174 + The opinion of multiple people carries exponentially more weight. 175 + 171 176 Different developers will review code from different points of view. Some 172 177 are mostly concerned with coding style and whether code lines have trailing 173 178 white space. Others will focus primarily on whether the change implemented ··· 183 176 documentation, adverse effects on performance, user-space ABI changes, etc. 184 177 All types of review, if they lead to better code going into the kernel, are 185 178 welcome and worthwhile. 179 + 180 + There is no strict requirement to use specific tags like ``Reviewed-by``. 181 + In fact reviews in plain English are more informative and encouraged 182 + even when a tag is provided, e.g. "I looked at aspects A, B and C of this 183 + submission and it looks good to me." 184 + Some form of a review message or reply is obviously necessary otherwise 185 + maintainers will not know that the reviewer has looked at the patch at all! 186 + 187 + Last but not least patch review may become a negative process, focused 188 + on pointing out problems. Please throw in a compliment once in a while, 189 + particularly for newbies!
+15
Documentation/process/maintainer-netdev.rst
··· 441 441 new ``netdevsim`` features must be accompanied by selftests under 442 442 ``tools/testing/selftests/``. 443 443 444 + Reviewer guidance 445 + ----------------- 446 + 447 + Reviewing other people's patches on the list is highly encouraged, 448 + regardless of the level of expertise. For general guidance and 449 + helpful tips please see :ref:`development_advancedtopics_reviews`. 450 + 451 + It's safe to assume that netdev maintainers know the community and the level 452 + of expertise of the reviewers. The reviewers should not be concerned about 453 + their comments impeding or derailing the patch flow. 454 + 455 + Less experienced reviewers are highly encouraged to do more in-depth 456 + review of submissions and not focus exclusively on trivial or subjective 457 + matters like code formatting, tags etc. 458 + 444 459 Testimonials / feedback 445 460 ----------------------- 446 461