Re: [RFC PATCH 00/11] docs: remove submitting-drivers.rst

From: Jonathan Corbet <corbet@lwn.net>
To: Lukas Bulwahn <lukas.bulwahn@gmail.com>,
	Federico Vaga <federico.vaga@vaga.pv.it>,
	Alex Shi <alexs@kernel.org>, Yanteng Si <siyanteng@loongson.cn>,
	Hu Haowen <src.res@email.cn>,
	linux-doc@vger.kernel.org,
	linux-doc-tw-discuss@lists.sourceforge.net
Cc: Jean Delvare <jdelvare@suse.com>,
	Guenter Roeck <linux@roeck-us.net>,
	linux-hwmon@vger.kernel.org, kernel-janitors@vger.kernel.org,
	linux-kernel@vger.kernel.org,
	Lukas Bulwahn <lukas.bulwahn@gmail.com>
Subject: Re: [RFC PATCH 00/11] docs: remove submitting-drivers.rst
Date: Thu, 30 Jun 2022 11:26:42 -0600	[thread overview]
Message-ID: <87y1xenju5.fsf@meer.lwn.net> (raw)
In-Reply-To: <20220627151819.22694-1-lukas.bulwahn@gmail.com>

Lukas Bulwahn <lukas.bulwahn@gmail.com> writes:

> Dear Jonathan, dear Federico, dear Alex, dear Yanteng, dear Hu,
>
> Here is an attempt to delete submitting-drivers with some improvements
> and clean-up in other documentation places to convince ourselves that
> nothing valuable is lost when deleting this checklist.

I am totally in favor of doing this; that document has not served any
real purpose for a long time.  Resend with the translation tweaks and
such, and I'll happily apply it.

> As future work---with this one submitting checklist gone---I see the harder
> follow-up task to synchronize and clean up the various submission hints/
> guidelines/checklists in the remaining kernel documentation that partly
> overlap and differ in detail, their structure (unstructured, unordered
> lists vs. sections and subsections) and their state of being outdated:
>
>   Documentation/process/submit-checklist.rst
>   Documentation/process/submitting-patches.rst
>   MAINTAINERS#Tips for patch submitters
>
> My next task at hand is to read through all three documents, figure out
> what still applies and what is outdated, determine a good common structure
> for all three documents, include cross-links and make them to some extent
> follow a clear consistent policy. E.g., one document is a more detailed
> description of everything mentioned in the short list of another document.
> I will try to work through that in the next months or motivate and guide
> some colleague or mentee to work together with me on that.

This seems like a good exercise as well.  I think the MAINTAINERS text
should go away entirely, that's not really an appropriate place for it.
submit-checklist.rst hasn't seen any real attention for some time; I'm
not sure how useful it really is.

What I would *really* like is a version of submitting-patches.rst that
is not a "War and Peace" sort of reading experience.  That is a lot for
somebody to get through before they can send their first patch...but
it's not easy to make it shorter without losing important stuff.

Thanks,

jon