Re: [PATCH RFC net] docs: netdev: document guidance on cleanup patches

[Simon Horman <horms@kernel.org>]

On Mon, Oct 07, 2024 at 08:24:30AM -0700, Jakub Kicinski wrote:
> On Fri, 04 Oct 2024 10:49:53 +0100 Simon Horman wrote:
> > 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.
> > 
> > --
> > I did think this was already documented. And perhaps it is.
> > But I was unable to find it after a quick search.
> 
> Thanks a lot for documenting it, this is great!
> All the suggestions below are optional, happy to merge as is.
> 
> > +Clean-Up Patches
> > +~~~~~~~~~~~~~~~~
> 
> nit: other sections use sentence-like capitalization (only capitalizing
> the first word), is that incorrect? Or should we ay "Clean-up patches"
> here?

I think we should be consistent here
(I'm intentionally avoiding answering what is correct :)

> 
> > +Netdev discourages patches which perform simple clean-ups, which are not in
> > +the context of other work. For example addressing ``checkpatch.pl``
> > +warnings, or :ref:`local variable ordering<rcs>` issues. This is because it
> > +is felt that the churn that such changes produce comes at a greater cost
> > +than the value of such clean-ups.
> 
> Should we add "conversions to managed APIs"? It's not a recent thing,
> people do like to post patches doing bulk conversions which bring very
> little benefit.

Well yes, I agree that is well established, and a common target of patches.
But isn't that covered by the previous section?

   "Using device-managed and cleanup.h constructs
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   "Netdev remains skeptical about promises of all “auto-cleanup” APIs,
    including even devm_ helpers, historically. They are not the preferred
    style of implementation, merely an acceptable one.

    ...

   https://docs.kernel.org/process/maintainer-netdev.html#using-device-managed-and-cleanup-h-constructs

We could merge or otherwise rearrange that section with the one proposed by
this patch. But I didn't feel it was necessary last week.

> On the opposite side we could mention that spelling fixes are okay.
> Not sure if that would muddy the waters too much..

I think we can and should. Perhaps another section simply stating
that spelling (and grammar?) fixes are welcome.