Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
MIME-Version: 1.0
References: <20220627151819.22694-1-lukas.bulwahn@gmail.com> <87y1xenju5.fsf@meer.lwn.net>
In-Reply-To: <87y1xenju5.fsf@meer.lwn.net>
From:   Lukas Bulwahn <lukas.bulwahn@gmail.com>
Date:   Mon, 4 Jul 2022 15:02:01 +0200
Message-ID: <CAKXUXMwBV79aWBByBaq+uicpKB4pJG8Nd=RWT55bVcqkV4YR9Q@mail.gmail.com>
Subject: Re: [RFC PATCH 00/11] docs: remove submitting-drivers.rst
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     Federico Vaga <federico.vaga@vaga.pv.it>,
        Alex Shi <alexs@kernel.org>,
        Yanteng Si <siyanteng@loongson.cn>,
        Hu Haowen <src.res@email.cn>,
        "open list:DOCUMENTATION" <linux-doc@vger.kernel.org>,
        linux-doc-tw-discuss@lists.sourceforge.net,
        Jean Delvare <jdelvare@suse.com>,
        Guenter Roeck <linux@roeck-us.net>,
        linux-hwmon@vger.kernel.org,
        kernel-janitors <kernel-janitors@vger.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

On Thu, Jun 30, 2022 at 7:26 PM Jonathan Corbet <corbet@lwn.net> wrote:
>
> 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.
>

I send out the tuned patch series, ready to be picked:

https://lore.kernel.org/linux-doc/20220704122537.3407-1-lukas.bulwahn@gmail.com/

> > 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.
>

We share the same vision. I will try to propose a good submit
checklist that covers the content of submitting-patches.rst as a short
bullet-point list. That should then also cover the valuable (not
outdated) parts of Documentation/process/submit-checklist.rst and
'MAINTAINERS#Tips for patch submitters' as well. With that new
checklist included with proper references and considered good by our
peers, we will use the earned credits to delete the previous tips and
checklists.

Lukas