| Message ID | 20220627151819.22694-1-lukas.bulwahn@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | docs: remove submitting-drivers.rst | expand |
On 6/27/22 22:18, Lukas Bulwahn wrote: > 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. > Hi, I think MAINTAINERS#Tips for patch submitters contains redundant info compared to other submission guidelines, and some tips there are outdated (like using `diff -u` instead of git). For consistency, that section can be removed (in your next RFC series).
On Tue, Jun 28, 2022 at 4:50 AM Bagas Sanjaya <bagasdotme@gmail.com> wrote: > > On 6/27/22 22:18, Lukas Bulwahn wrote: > > 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. > > > > Hi, > > I think MAINTAINERS#Tips for patch submitters contains redundant info > compared to other submission guidelines, and some tips there are outdated > (like using `diff -u` instead of git). For consistency, that section can > be removed (in your next RFC series). > Thanks for the suggestion. I noticed the outdated hint on 'diff -u' as well. I was considering replacing it with 'Use git format-patch and git send-email to get submitting patches via email right.'. (or to avoid some pitfalls when submitting patches, I have not decided yet). But let us first clean up the submitting-drivers with this patch series and get this done. Lukas > -- > An old man doll... just what I always wanted! - Clara
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
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
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 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. I hope that patches 1 to 6 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. ja_JP/SubmittingPatches:ているなら、Documentation/process/submitting-drivers.rst にも目を通してください。 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. Other topics I encountered: - in translations/it_IT/process/submitting-patches.rst, the guideline link for patches to device tree binding seems wrong (although I do not speak Italian, so it is also just a guess). 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. 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. 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 | 3 +- .../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 | 2 +- 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, 64 insertions(+), 610 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