Message-Id: <20220704122537.3407-1-lukas.bulwahn@gmail.com>
Date:   Mon,  4 Jul 2022 14:25:26 +0200
From:   Lukas Bulwahn <lukas.bulwahn@...il.com>
To:     Jonathan Corbet <corbet@....net>,
        Federico Vaga <federico.vaga@...a.pv.it>,
        Alex Shi <alexs@...nel.org>,
        Yanteng Si <siyanteng@...ngson.cn>,
        Hu Haowen <src.res@...il.cn>, linux-doc@...r.kernel.org,
        linux-doc-tw-discuss@...ts.sourceforge.net
Cc:     Jean Delvare <jdelvare@...e.com>,
        Guenter Roeck <linux@...ck-us.net>,
        linux-hwmon@...r.kernel.org, kernel-janitors@...r.kernel.org,
        linux-kernel@...r.kernel.org,
        Lukas Bulwahn <lukas.bulwahn@...il.com>
Subject: [PATCH 00/11] docs: remove submitting-drivers.rst

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.

Patch 1, 2 and 3 is just basic clean-up before adding a new reference (see
Patch 4). Patch 4 adds the one reference from submitting-drivers, not
already mentioned elsewhere in the repository. Patch 5 updates a confusing
statement in devices.rst from earlier .txt/.tex distinction times to the
new state now with Sphinx & .rst.

Patch 6 finally deletes the outdated document, with a cross-check what is
covered elsewhere and few open questions (see below).

Patch 7 and 8 have been reworked with the native-speaking doc maintainers;
they cause no new warnings and are ready to pick,

Patch 9 to 11 are weak attempts to adjust the translation, but they need
to be taken further by others due to my lack of knowledge on the other
languages.  They would currently also cause new warnings in the doc-build
right now. They should not be picked if there is no one to continue
to adjust the text and fix the warnings on broken references.

I hope that patches 1 to 8 can be picked into doc-next, and then we see
how to fix up the translations as well.


Further open considerations:

  - Should we add some subsection/paragraph on Testing to "A guide on
    kernel development process", which then further refers to
    power/drivers-testing.rst for testing the power management of the
    driver?

    (I am bit surprised that code-checking tools are mentioned, but not
    much more on actual kernel testing is mentioned there.)

  - Should we be a bit more explicit on how and when to add a MAINTAINERS
    entry, besides the short note in 6.Followthrough.rst?

  - Translations of submitting-patches.rst and 8.Conclusion.rst in Asian
    languages include a reference to submitting-drivers, I cannot adjust
    the text due to my lack of understanding of the surrounding text.
 
    zh_CN/process/8.Conclusion.rst:和 :ref:`Documentation/translations/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>`
    zh_CN/process/submitting-patches.rst::ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
    zh_TW/process/8.Conclusion.rst:和 :ref:`Documentation/translations/zh_TW/process/submitting-drivers.rst <tw_submittingdrivers>`
    zh_TW/process/submitting-patches.rst::ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`

    This currently lead to some new warnings in this patch series. I hope
    some native speakers of those languages can help out here. The other
    references were adjusted on a best guess of the text, which should be
    confirmed by native-speaking reviewers.

Generally, I hope we are now all well-convinced to delete submitting-drivers.

Anything else needed to be convinced? I put already some thought into it,
and I am willing to add more content in other documents to properly get rid
of this outdated one here, or just starting writing a good new checklist
for driver submission that reflect what the majority of maintainers want
to see submitters do.

Link to RFC patch series: 
  https://lore.kernel.org/linux-doc/20220627151819.22694-1-lukas.bulwahn@gmail.com/

rfc -> v1: improved Italian and Japanese translation


Best regards,

Lukas


Lukas Bulwahn (11):
  docs: kernel-docs: order reference from newest to oldest
  docs: kernel-docs: shorten the lengthy doc title
  docs: kernel-docs: reflect that it is community-maintained
  docs: kernel-docs: add a reference mentioned in submitting-drivers.rst
  docs: admin: devices:  drop confusing outdated statement on Latex
  docs: process: remove outdated submitting-drivers.rst
  docs: it_IT: align to submitting-drivers removal
  docs: ja_JP: howto: remove reference to removed submitting-drivers
  docs: ko_KR: howto: remove reference to removed submitting-drivers
  docs: zh_CN: align to submitting-drivers removal
  docs: zh_TW: align to submitting-drivers removal

 Documentation/admin-guide/devices.rst         |   7 +-
 Documentation/hwmon/submitting-patches.rst    |   1 -
 Documentation/kernel-hacking/hacking.rst      |   3 +-
 Documentation/process/5.Posting.rst           |   3 +-
 Documentation/process/8.Conclusion.rst        |  16 +-
 Documentation/process/howto.rst               |   4 +-
 Documentation/process/index.rst               |   1 -
 Documentation/process/kernel-docs.rst         |  62 +++---
 Documentation/process/submitting-drivers.rst  | 194 ------------------
 Documentation/process/submitting-patches.rst  |   5 +-
 .../it_IT/kernel-hacking/hacking.rst          |   3 +-
 .../translations/it_IT/process/5.Posting.rst  |   5 +-
 .../it_IT/process/8.Conclusion.rst            |   5 +-
 .../translations/it_IT/process/howto.rst      |   3 +-
 .../translations/it_IT/process/index.rst      |   1 -
 .../it_IT/process/submitting-drivers.rst      |  16 --
 .../it_IT/process/submitting-patches.rst      |   6 +-
 Documentation/translations/ja_JP/howto.rst    |   4 +-
 Documentation/translations/ko_KR/howto.rst    |   2 +-
 .../zh_CN/kernel-hacking/hacking.rst          |   3 +-
 .../translations/zh_CN/process/5.Posting.rst  |   3 +-
 .../translations/zh_CN/process/howto.rst      |   1 -
 .../translations/zh_CN/process/index.rst      |   1 -
 .../zh_CN/process/submitting-drivers.rst      | 160 ---------------
 .../translations/zh_TW/process/5.Posting.rst  |   3 +-
 .../translations/zh_TW/process/howto.rst      |   1 -
 .../translations/zh_TW/process/index.rst      |   1 -
 .../zh_TW/process/submitting-drivers.rst      | 164 ---------------
 28 files changed, 66 insertions(+), 612 deletions(-)
 delete mode 100644 Documentation/process/submitting-drivers.rst
 delete mode 100644 Documentation/translations/it_IT/process/submitting-drivers.rst
 delete mode 100644 Documentation/translations/zh_CN/process/submitting-drivers.rst
 delete mode 100644 Documentation/translations/zh_TW/process/submitting-drivers.rst

-- 
2.17.1

Powered by blists - more mailing lists