The purpose of this section is to document what is the current practice
regarding clean-up patches which address checkpatch warnings and similar
problems. I feel there is a value in having this documented so others
can easily refer to it.
Clearly this topic is subjective. And to some extent the current
practice discourages a wider range of patches than is described here.
But I feel it is best to start somewhere, with the most well established
part of the current practice.
Signed-off-by: Simon Horman <horms@kernel.org>
Link: https://patch.msgid.link/20241009-doc-mc-clean-v2-1-e637b665fa81@kernel.org
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Document what was discussed multiple times on list and various
virtual / in-person conversations. guard() being okay in functions
<= 20 LoC is a bit of my own invention. If the function is trivial
it should be fine, but feel free to disagree :)
We'll obviously revisit this guidance as time passes and we and other
subsystems get more experience.
Reviewed-by: Eric Dumazet <edumazet@google.com>
Reviewed-by: Nikolay Aleksandrov <razor@blackwall.org>
Reviewed-by: Andrew Lunn <andrew@lunn.ch>
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Link: https://patch.msgid.link/20240830171443.3532077-1-kuba@kernel.org
Signed-off-by: Paolo Abeni <pabeni@redhat.com>
As we discussed in the room at netdevconf earlier this week,
drop the requirement for special comment style for netdev.
For checkpatch, the general check accepts both right now, so
simply drop the special request there as well.
Acked-by: Stephen Hemminger <stephen@networkplumber.org>
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Acked-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
around, mostly more of the usual:
- More Spanish, Italian, and Chinese translations
- A new script, scripts/checktransupdate.py, can be used to see which
commits have touched an (English) document since a given translation was
last updated.
- A couple of "best practices" suggestions (on Link: tags and off-list
discussions) that were not entirely at consensus level, but I concluded
they were close enough to accept.
- Some nice cleanups removing documentation for kernel parameters that have
not been recognized for ... a long time.
...along with the usual updates, typo fixes, and such.
-----BEGIN PGP SIGNATURE-----
iQFDBAABCAAtFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAmaZbLMPHGNvcmJldEBs
d24ubmV0AAoJEBdDWhNsDH5Y7PkH/jk1LverE9XOXZO5Uq+eEwWlNI2khjQ0hI+M
b0GZlIfeHsted0I8CsYapbehhqve700QJQ8/dmst9jPEwiQq9omSNp8ux/mpIvk+
OjeCLoApZ1slYj9HeiDkwuLDw5o0bKOep6fmrlnnc2uJezqBbjSLmUgocqfCnZb1
fHikvSP0McKjffei76+KH1PYK8BmJwredsHvmfehLJpETHQhe11tO3byPM48iLcy
mybECacqB8zfy7wkvVTWhd+QFkT7x+BE4g/Z07L8z4m9HRxmJbV6EJF1GPlpDJWZ
TV0u86cOAlpMeUy44pfUnej6E9ntafeaHmX7CJpcgskh3h4J/qc=
=uk19
-----END PGP SIGNATURE-----
Merge tag 'docs-6.11' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"Nothing hugely exciting happening in the documentation tree this time
around, mostly more of the usual:
- More Spanish, Italian, and Chinese translations
- A new script, scripts/checktransupdate.py, can be used to see which
commits have touched an (English) document since a given
translation was last updated.
- A couple of "best practices" suggestions (on Link: tags and
off-list discussions) that were not entirely at consensus level,
but I concluded they were close enough to accept.
- Some nice cleanups removing documentation for kernel parameters
that have not been recognized for ... a long time.
...along with the usual updates, typo fixes, and such"
* tag 'docs-6.11' of git://git.lwn.net/linux: (57 commits)
Documentation: Document user_events ioctl code
docs/pinctrl: fix typo in mapping example
docs: maintainer: discourage taking conversations off-list
docs: driver-model: platform: update the definition of platform_driver
docs/sp_SP: Add translation for scheduler/sched-design-CFS.rst
writing_musb_glue_layer.rst: Fix broken URL
zh_CN/admin-guide: one typo fix
docs/zh_CN/virt: Update the translation of guest-halt-polling.rst
Documentation: add reference from dynamic debug to loglevel kernel params
Documentation: best practices for using Link trailers
Documentation: fix links to mailing list services
Documentation: exception-tables.rst: Fix the wrong steps referenced
docs/zh_CN: add process/researcher-guidelines Chinese translation
Documentation/tools/rv: fix document header
docs/sp_SP: Add translation of process/maintainer-kvm-x86.rst
docs/admin-guide/mm: correct typo 'quired' to 'queried'
Add libps2 to the input section of driver-api
Docs/mm/index: move allocation profiling document to unsorted documents chapter
Docs/mm/index: rename 'Legacy Documentation' to 'Unsorted Documentation'
Docs/mm/index: Remove 'Memory Management Guide' chapter marker
...
There have been some changes to the way mailing lists are hosted at
kernel.org. This patch does the following:
1. fixes links that are pointing at the outdated resources
2. removes an outdated patchbomb admonition
We still don't particularly want or welcome huge patchbombs, but they
are less likely to overload our systems.
Acked-by: Dan Williams <dan.j.williams@intel.com>
Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Reviewed-by: Carlos Bilbao <carlos.bilbao.osdev@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240619-docs-patch-msgid-link-v2-1-72dd272bfe37@linuxfoundation.org
Netronome graciously transferred the original NIPA repo
to our new netdev umbrella org. Link to that instead of
my private fork.
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Reviewed-by: Simon Horman <horms@kernel.org>
Link: https://lore.kernel.org/r/20240216161945.2208842-1-kuba@kernel.org
Signed-off-by: Paolo Abeni <pabeni@redhat.com>
There has been more than a few threads which went idle before
the merge window and now people came back to them and started
asking about next steps.
We currently tell people to be patient and not to repost too
often. Our "not too often", however, is still a few orders of
magnitude faster than other subsystems. Or so I feel after
hearing people talk about review rates at LPC.
Clarify in the doc that if the discussion went idle for a week
on netdev, 95% of the time there's no point waiting longer.
Link: https://lore.kernel.org/r/20231120200109.620392-1-kuba@kernel.org
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
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>
Some corporate proxies block our current NIPA URLs because
they use a free / shady DNS domain. As suggested by Jesse
we got a new DNS entry from Konstantin - netdev.bots.linux.dev,
use it.
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Reviewed-by: Simon Horman <horms@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
The patchwork states are largely self-explanatory but small
ambiguities may still come up. Document how we interpret
the states in networking.
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
It's somewhat unfortunate but with (my?) the current tooling
if people post new versions of a set in reply to an old version
managing the review queue gets difficult. So recommend against it.
Reviewed-by: Martin Habets <habetsm.xilinx@gmail.com>
Link: https://lore.kernel.org/r/20230823154922.1162644-1-kuba@kernel.org
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Reword slightly now that all MAINTAINERS have access to the commands.
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Reviewed-by: Simon Horman <simon.horman@corigine.com>
Signed-off-by: David S. Miller <davem@davemloft.net>
We had a good run, but after 4 weeks of use we heard someone
asking about pw-bot commands. Let's explain its existence
in the docs. It's not a complete documentation but hopefully
it's enough for the casual contributor. The project and scope
are in flux so the details would likely become out of date,
if we were to document more in depth.
Link: https://lore.kernel.org/all/20230522140057.GB18381@nucnuc.mle/
Reviewed-by: Andrew Lunn <andrew@lunn.ch>
Reviewed-by: Simon Horman <simon.horman@corigine.com>
Link: https://lore.kernel.org/r/20230522230903.1853151-1-kuba@kernel.org
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
We don't state explicitly that reverts need to be submitted
as a patch. It occasionally comes up.
Reviewed-by: Jacob Keller <jacob.e.keller@intel.com>
Reviewed-by: Florian Fainelli <f.fainelli@gmail.com>
Link: https://lore.kernel.org/r/20230327172646.2622943-1-kuba@kernel.org
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
One of the most commonly asked questions is "I answered all questions
and don't need to make any code changes, why was the patch not applied".
Document our time honored tradition of asking people to repost with
improved commit messages, to record the answers to reviewer questions.
Take this opportunity to also recommend a change log format.
Link: https://lore.kernel.org/r/20230322231202.265835-1-kuba@kernel.org
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
The netdev-FAQ document has grown over the years to the point
where finding information in it is somewhat challenging.
The length of the questions prevents readers from locating
content that's relevant at a glance.
Convert to a more standard documentation format with sections
and sub-sections rather than questions and answers.
The content edits are limited to what's necessary to change
the format, and very minor clarifications.
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Andrew Lunn <andrew@lunn.ch>
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
Subsequent changes will reformat the doc away from FAQ.
To make that more readable perform the pure section moves now.
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Andrew Lunn <andrew@lunn.ch>
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
Some of us gotten used to producing large quantities of peer feedback
at work, every 3 or 6 months. Extending the same courtesy to community
members seems like a logical step. It may be hard for some folks to
get validation of how important their work is internally, especially
at smaller companies which don't employ many kernel experts.
The concept of "peer feedback" may be a hyperscaler / silicon valley
thing so YMMV. Hopefully we can build more context as we go.
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
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>
Signed-off-by: David S. Miller <davem@davemloft.net>
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>
Signed-off-by: David S. Miller <davem@davemloft.net>
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>
Signed-off-by: David S. Miller <davem@davemloft.net>
The documentation for the tip tree is really in quite a similar
spirit to the netdev-FAQ. Move the netdev-FAQ to the process docs
as well.
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Reviewed-by: Florian Fainelli <f.fainelli@gmail.com>
Signed-off-by: Paolo Abeni <pabeni@redhat.com>
