From 9c03bc90c0651647a6f17d532533fad9ac1d5d9e Mon Sep 17 00:00:00 2001 From: Conor Dooley Date: Thu, 16 May 2024 16:35:23 +0100 Subject: Documentation: process: Revert "Document suitability of Proton Mail for kernel development" Revert commit 1d2ed9234c85 ("Documentation: process: Document suitability of Proton Mail for kernel development") as Proton disabled WKD for kernel.org addresses as a result of some interaction with Konstantin on social.kernel.org Signed-off-by: Conor Dooley Reviewed-by: Kanak Shilledar Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240516-groin-slingshot-c3c3734d2f10@spud --- Documentation/process/email-clients.rst | 20 -------------------- 1 file changed, 20 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst index 471e1f93fa09..fc2c46f3f82d 100644 --- a/Documentation/process/email-clients.rst +++ b/Documentation/process/email-clients.rst @@ -350,23 +350,3 @@ although tab2space problem can be solved with external editor. Another problem is that Gmail will base64-encode any message that has a non-ASCII character. That includes things like European names. - -Proton Mail -*********** - -Proton Mail has a "feature" where it looks up keys using Web Key Directory -(WKD) and encrypts mail to any recipients for which it finds a key. -Kernel.org publishes the WKD for all developers who have kernel.org accounts. -As a result, emails sent using Proton Mail to kernel.org addresses will be -encrypted. -Unfortunately, Proton Mail does not provide a mechanism to disable the -automatic encryption, viewing it as a privacy feature. -The automatic encryption feature is also enabled for mail sent via the Proton -Mail Bridge, so this affects all outgoing messages, including patches sent with -``git send-email``. -Encrypted mail adds unnecessary friction, as other developers may not have mail -clients, or tooling, configured for use with encrypted mail and some mail -clients may encrypt responses to encrypted mail for all recipients, including -the mailing lists. -Unless a way to disable this "feature" is introduced, Proton Mail is unsuited -to kernel development. -- cgit v1.2.3 From b80103a2dfe6a9fcc2ea037e9f26c72eae24252c Mon Sep 17 00:00:00 2001 From: Karel Balej Date: Mon, 13 May 2024 10:41:10 +0200 Subject: docs: handling-regressions.rst: recommend using "Closes:" tags Update the handling-regressions guide to recommend using "Closes:" tags rather than "Link:" when referencing fixed reports. The latter was used originally but now is only recommended when the given patch only fixes part of the issue, as described in submitting-patches. Briefly mention that and also note that regzbot currently doesn't make a distinction. Also fix a typo. Acked-by: Thorsten Leemhuis Signed-off-by: Karel Balej Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240513084145.2460-1-balejk@matfyz.cz --- Documentation/process/handling-regressions.rst | 30 +++++++++++++++----------- 1 file changed, 18 insertions(+), 12 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst index 49ba1410cfce..1f5ab49c48a4 100644 --- a/Documentation/process/handling-regressions.rst +++ b/Documentation/process/handling-regressions.rst @@ -40,10 +40,13 @@ The important bits (aka "The TL;DR") #regzbot from: Some N. Ice Human #regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789 -#. When submitting fixes for regressions, add "Link:" tags to the patch +#. When submitting fixes for regressions, add "Closes:" tags to the patch description pointing to all places where the issue was reported, as mandated by Documentation/process/submitting-patches.rst and - :ref:`Documentation/process/5.Posting.rst `. + :ref:`Documentation/process/5.Posting.rst `. If you are + only fixing part of the issue that caused the regression, you may use + "Link:" tags instead. regzbot currently makes no distinction between the + two. #. Try to fix regressions quickly once the culprit has been identified; fixes for most regressions should be merged within two weeks, but some need to be @@ -91,10 +94,10 @@ When doing either, consider making the Linux kernel regression tracking bot Note the caret (^) before the "introduced": it tells regzbot to treat the parent mail (the one you reply to) as the initial report for the regression you want to see tracked; that's important, as regzbot will later look out - for patches with "Link:" tags pointing to the report in the archives on + for patches with "Closes:" tags pointing to the report in the archives on lore.kernel.org. - * When forwarding a regressions reported to a bug tracker, include a paragraph + * When forwarding a regression reported to a bug tracker, include a paragraph with these regzbot commands:: #regzbot introduced: 1f2e3d4c5b6a @@ -102,7 +105,7 @@ When doing either, consider making the Linux kernel regression tracking bot #regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789 Regzbot will then automatically associate patches with the report that - contain "Link:" tags pointing to your mail or the mentioned ticket. + contain "Closes:" tags pointing to your mail or the mentioned ticket. What's important when fixing regressions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -112,10 +115,14 @@ remember to do what Documentation/process/submitting-patches.rst, :ref:`Documentation/process/5.Posting.rst `, and Documentation/process/stable-kernel-rules.rst already explain in more detail: - * Point to all places where the issue was reported using "Link:" tags:: + * Point to all places where the issue was reported using "Closes:" tags:: - Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ - Link: https://bugzilla.kernel.org/show_bug.cgi?id=1234567890 + Closes: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + Closes: https://bugzilla.kernel.org/show_bug.cgi?id=1234567890 + + If you are only fixing part of the issue, you may use "Link:" instead as + described in the first document mentioned above. regzbot currently treats + both of these equivalently and considers the linked reports as resolved. * Add a "Fixes:" tag to specify the commit causing the regression. @@ -126,7 +133,7 @@ All this is expected from you and important when it comes to regression, as these tags are of great value for everyone (you included) that might be looking into the issue weeks, months, or years later. These tags are also crucial for tools and scripts used by other kernel developers or Linux distributions; one of -these tools is regzbot, which heavily relies on the "Link:" tags to associate +these tools is regzbot, which heavily relies on the "Closes:" tags to associate reports for regression with changes resolving them. Expectations and best practices for fixing regressions @@ -326,7 +333,7 @@ How does regression tracking work with regzbot? The bot watches for replies to reports of tracked regressions. Additionally, it's looking out for posted or committed patches referencing such reports -with "Link:" tags; replies to such patch postings are tracked as well. +with "Closes:" tags; replies to such patch postings are tracked as well. Combined this data provides good insights into the current state of the fixing process. @@ -338,8 +345,7 @@ take care of that using ``#regzbot ^introduced``. For developers there normally is no extra work involved, they just need to make sure to do something that was expected long before regzbot came to light: add -"Link:" tags to the patch description pointing to all reports about the issue -fixed. +links to the patch description pointing to all reports about the issue fixed. Do I have to use regzbot? ~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 627395716cc36eff127aa81997b535818ab003fa Mon Sep 17 00:00:00 2001 From: Dmitry Baryshkov Date: Thu, 9 May 2024 16:31:05 +0300 Subject: docs: document python version used for compilation The drm/msm driver had adopted using Python3 script to generate register header files instead of shipping pre-generated header files. Document the minimal Python version supported by the script. Signed-off-by: Dmitry Baryshkov Reviewed-by: Abhinav Kumar Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240509-python-version-v1-1-a7dda3a95b5f@linaro.org --- Documentation/process/changes.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/process') diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 5685d7bfe4d0..8d225a9f65a2 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -63,6 +63,7 @@ cpio any cpio --version GNU tar 1.28 tar --version gtags (optional) 6.6.5 gtags --version mkimage (optional) 2017.01 mkimage --version +Python (optional) 3.5.x python3 --version ====================== =============== ======================================== .. [#f1] Sphinx is needed only to build the Kernel documentation -- cgit v1.2.3 From 346bc3d8cddb035ab85daa3b29b47433860ee542 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Mon, 24 Jun 2024 11:53:06 -0700 Subject: Docs/process/index: Remove unaligned-memory-access from 'Other material' 'unaligned-memory-access document' is linked on 'Other material' section of 'core-api/index', which is for unsorted documents. But it is actually well organized under 'core-api/' directory, and linked on the 'core-api/index'. Remove it from 'Other material' section of 'process/index' document. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240624185312.94537-2-sj@kernel.org --- Documentation/process/index.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation/process') diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index de9cbb7bd7eb..f66f9cbd0300 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -116,7 +116,6 @@ lack of a better place. magic-number clang-format ../arch/riscv/patch-acceptance - ../core-api/unaligned-memory-access .. only:: subproject and html -- cgit v1.2.3 From 7400d25a0a5cb2a1a782c4c49e6c8f883e5184d0 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Mon, 24 Jun 2024 11:53:07 -0700 Subject: Docs/process/index: Remove riscv/patch-acceptance from 'Other material' section 'patch-acceptance' on 'Other material' section of 'process/index', which is for unsorted documents, is actually well organized under 'arch/riscv/' directory, and linked on the index document of the directory. Remove it from the 'Other material' section. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240624185312.94537-3-sj@kernel.org --- Documentation/process/index.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation/process') diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index f66f9cbd0300..08b4eb1e9118 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -115,7 +115,6 @@ lack of a better place. magic-number clang-format - ../arch/riscv/patch-acceptance .. only:: subproject and html -- cgit v1.2.3 From f9a4f4a0e1f5d8033d30d50f59ada1666a5cf38d Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Mon, 24 Jun 2024 11:53:08 -0700 Subject: Docs: Move magic-number from process to staging 'Other material' section on 'process/index' is for unsorted documents. However we also have a dedicated place for the purpose, 'staging/'. Move 'magic-number' from the section to 'staging/' directory. Signed-off-by: SeongJae Park Acked-by: Federico Vaga Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240624185312.94537-4-sj@kernel.org --- Documentation/process/index.rst | 1 - Documentation/process/magic-number.rst | 84 ---------------------- Documentation/staging/index.rst | 1 + Documentation/staging/magic-number.rst | 84 ++++++++++++++++++++++ .../translations/it_IT/process/magic-number.rst | 2 +- .../translations/sp_SP/process/magic-number.rst | 2 +- .../translations/zh_CN/process/magic-number.rst | 2 +- .../translations/zh_TW/process/magic-number.rst | 2 +- 8 files changed, 89 insertions(+), 89 deletions(-) delete mode 100644 Documentation/process/magic-number.rst create mode 100644 Documentation/staging/magic-number.rst (limited to 'Documentation/process') diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 08b4eb1e9118..fb089bf9d6a8 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -113,7 +113,6 @@ lack of a better place. .. toctree:: :maxdepth: 1 - magic-number clang-format .. only:: subproject and html diff --git a/Documentation/process/magic-number.rst b/Documentation/process/magic-number.rst deleted file mode 100644 index 7029c3c084ee..000000000000 --- a/Documentation/process/magic-number.rst +++ /dev/null @@ -1,84 +0,0 @@ -.. _magicnumbers: - -Linux magic numbers -=================== - -This file is a registry of magic numbers which are in use. When you -add a magic number to a structure, you should also add it to this -file, since it is best if the magic numbers used by various structures -are unique. - -It is a **very** good idea to protect kernel data structures with magic -numbers. This allows you to check at run time whether (a) a structure -has been clobbered, or (b) you've passed the wrong structure to a -routine. This last is especially useful --- particularly when you are -passing pointers to structures via a void * pointer. The tty code, -for example, does this frequently to pass driver-specific and line -discipline-specific structures back and forth. - -The way to use magic numbers is to declare them at the beginning of -the structure, like so:: - - struct tty_ldisc { - int magic; - ... - }; - -Please follow this discipline when you are adding future enhancements -to the kernel! It has saved me countless hours of debugging, -especially in the screwy cases where an array has been overrun and -structures following the array have been overwritten. Using this -discipline, these cases get detected quickly and safely. - -Changelog:: - - Theodore Ts'o - 31 Mar 94 - - The magic table is current to Linux 2.1.55. - - Michael Chastain - - 22 Sep 1997 - - Now it should be up to date with Linux 2.1.112. Because - we are in feature freeze time it is very unlikely that - something will change before 2.2.x. The entries are - sorted by number field. - - Krzysztof G. Baranowski - - 29 Jul 1998 - - Updated the magic table to Linux 2.5.45. Right over the feature freeze, - but it is possible that some new magic numbers will sneak into the - kernel before 2.6.x yet. - - Petr Baudis - - 03 Nov 2002 - - Updated the magic table to Linux 2.5.74. - - Fabian Frederick - - 09 Jul 2003 - - -===================== ================ ======================== ========================================== -Magic Name Number Structure File -===================== ================ ======================== ========================================== -PG_MAGIC 'P' pg_{read,write}_hdr ``include/linux/pg.h`` -APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` -FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` -SLIP_MAGIC 0x5302 slip ``drivers/net/slip.h`` -BAYCOM_MAGIC 0x19730510 baycom_state ``drivers/net/baycom_epp.c`` -HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state ``include/linux/hdlcdrv.h`` -KV_MAGIC 0x5f4b565f kernel_vars_s ``arch/mips/include/asm/sn/klkernvars.h`` -CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` -YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` -CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` -QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` -QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry ``drivers/scsi/arm/queue.c`` -NMI_MAGIC 0x48414d4d455201 nmi_s ``arch/mips/include/asm/sn/nmi.h`` -===================== ================ ======================== ========================================== diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst index 71592f3ce89b..77bae5e5328b 100644 --- a/Documentation/staging/index.rst +++ b/Documentation/staging/index.rst @@ -8,6 +8,7 @@ Unsorted Documentation crc32 lzo + magic-number remoteproc rpmsg speculation diff --git a/Documentation/staging/magic-number.rst b/Documentation/staging/magic-number.rst new file mode 100644 index 000000000000..7029c3c084ee --- /dev/null +++ b/Documentation/staging/magic-number.rst @@ -0,0 +1,84 @@ +.. _magicnumbers: + +Linux magic numbers +=================== + +This file is a registry of magic numbers which are in use. When you +add a magic number to a structure, you should also add it to this +file, since it is best if the magic numbers used by various structures +are unique. + +It is a **very** good idea to protect kernel data structures with magic +numbers. This allows you to check at run time whether (a) a structure +has been clobbered, or (b) you've passed the wrong structure to a +routine. This last is especially useful --- particularly when you are +passing pointers to structures via a void * pointer. The tty code, +for example, does this frequently to pass driver-specific and line +discipline-specific structures back and forth. + +The way to use magic numbers is to declare them at the beginning of +the structure, like so:: + + struct tty_ldisc { + int magic; + ... + }; + +Please follow this discipline when you are adding future enhancements +to the kernel! It has saved me countless hours of debugging, +especially in the screwy cases where an array has been overrun and +structures following the array have been overwritten. Using this +discipline, these cases get detected quickly and safely. + +Changelog:: + + Theodore Ts'o + 31 Mar 94 + + The magic table is current to Linux 2.1.55. + + Michael Chastain + + 22 Sep 1997 + + Now it should be up to date with Linux 2.1.112. Because + we are in feature freeze time it is very unlikely that + something will change before 2.2.x. The entries are + sorted by number field. + + Krzysztof G. Baranowski + + 29 Jul 1998 + + Updated the magic table to Linux 2.5.45. Right over the feature freeze, + but it is possible that some new magic numbers will sneak into the + kernel before 2.6.x yet. + + Petr Baudis + + 03 Nov 2002 + + Updated the magic table to Linux 2.5.74. + + Fabian Frederick + + 09 Jul 2003 + + +===================== ================ ======================== ========================================== +Magic Name Number Structure File +===================== ================ ======================== ========================================== +PG_MAGIC 'P' pg_{read,write}_hdr ``include/linux/pg.h`` +APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` +FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` +SLIP_MAGIC 0x5302 slip ``drivers/net/slip.h`` +BAYCOM_MAGIC 0x19730510 baycom_state ``drivers/net/baycom_epp.c`` +HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state ``include/linux/hdlcdrv.h`` +KV_MAGIC 0x5f4b565f kernel_vars_s ``arch/mips/include/asm/sn/klkernvars.h`` +CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` +YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` +CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` +QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` +QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry ``drivers/scsi/arm/queue.c`` +NMI_MAGIC 0x48414d4d455201 nmi_s ``arch/mips/include/asm/sn/nmi.h`` +===================== ================ ======================== ========================================== diff --git a/Documentation/translations/it_IT/process/magic-number.rst b/Documentation/translations/it_IT/process/magic-number.rst index ae92ab633c16..cd8f23571835 100644 --- a/Documentation/translations/it_IT/process/magic-number.rst +++ b/Documentation/translations/it_IT/process/magic-number.rst @@ -1,6 +1,6 @@ .. include:: ../disclaimer-ita.rst -:Original: :ref:`Documentation/process/magic-number.rst ` +:Original: :ref:`Documentation/staging/magic-number.rst ` :Translator: Federico Vaga .. _it_magicnumbers: diff --git a/Documentation/translations/sp_SP/process/magic-number.rst b/Documentation/translations/sp_SP/process/magic-number.rst index 32a99aac2f6c..beb4b4c1de11 100644 --- a/Documentation/translations/sp_SP/process/magic-number.rst +++ b/Documentation/translations/sp_SP/process/magic-number.rst @@ -1,6 +1,6 @@ .. include:: ../disclaimer-sp.rst -:Original: :ref:`Documentation/process/magic-number.rst ` +:Original: :ref:`Documentation/staging/magic-number.rst ` :Translator: Carlos Bilbao .. _sp_magicnumbers: diff --git a/Documentation/translations/zh_CN/process/magic-number.rst b/Documentation/translations/zh_CN/process/magic-number.rst index 4e4aeaca796c..4ebc84cc0c54 100644 --- a/Documentation/translations/zh_CN/process/magic-number.rst +++ b/Documentation/translations/zh_CN/process/magic-number.rst @@ -1,6 +1,6 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: Documentation/process/magic-number.rst +:Original: Documentation/staging/magic-number.rst :翻译: diff --git a/Documentation/translations/zh_TW/process/magic-number.rst b/Documentation/translations/zh_TW/process/magic-number.rst index 199cd5d63973..5582df6d7ca7 100644 --- a/Documentation/translations/zh_TW/process/magic-number.rst +++ b/Documentation/translations/zh_TW/process/magic-number.rst @@ -4,7 +4,7 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/process/magic-number.rst ` +:Original: :ref:`Documentation/staging/magic-number.rst ` 如果想評論或更新本文的內容，請直接發信到LKML。如果你使用英文交流有困難的話，也可 以向中文版維護者求助。如果本翻譯更新不及時或者翻譯存在問題，請聯繫中文版維護者:: -- cgit v1.2.3 From e3b10a02ca2fe1e27ee008e9fcd8cf7076f7f776 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Mon, 24 Jun 2024 11:53:09 -0700 Subject: Docs: Move clang-format from process/ to dev-tools/ 'clang-format' is on 'Other material' section of 'process/index', but it may fit more under 'dev-tools/' directory. Move it. Signed-off-by: SeongJae Park Acked-by: Miguel Ojeda Acked-by: Federico Vaga Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240624185312.94537-5-sj@kernel.org --- .clang-format | 2 +- Documentation/dev-tools/clang-format.rst | 184 +++++++++++++++++++++ Documentation/dev-tools/index.rst | 1 + Documentation/process/4.Coding.rst | 2 +- Documentation/process/clang-format.rst | 184 --------------------- Documentation/process/coding-style.rst | 2 +- Documentation/process/index.rst | 1 - .../translations/it_IT/process/clang-format.rst | 2 +- .../translations/sp_SP/process/coding-style.rst | 2 +- .../translations/zh_CN/process/4.Coding.rst | 2 +- .../translations/zh_CN/process/coding-style.rst | 2 +- .../translations/zh_TW/process/4.Coding.rst | 2 +- .../translations/zh_TW/process/coding-style.rst | 2 +- 13 files changed, 194 insertions(+), 194 deletions(-) create mode 100644 Documentation/dev-tools/clang-format.rst delete mode 100644 Documentation/process/clang-format.rst (limited to 'Documentation/process') diff --git a/.clang-format b/.clang-format index ccc9b93972a9..252820d9c80a 100644 --- a/.clang-format +++ b/.clang-format @@ -4,7 +4,7 @@ # # For more information, see: # -# Documentation/process/clang-format.rst +# Documentation/dev-tools/clang-format.rst # https://clang.llvm.org/docs/ClangFormat.html # https://clang.llvm.org/docs/ClangFormatStyleOptions.html # diff --git a/Documentation/dev-tools/clang-format.rst b/Documentation/dev-tools/clang-format.rst new file mode 100644 index 000000000000..1d089a847c1b --- /dev/null +++ b/Documentation/dev-tools/clang-format.rst @@ -0,0 +1,184 @@ +.. _clangformat: + +clang-format +============ + +``clang-format`` is a tool to format C/C++/... code according to +a set of rules and heuristics. Like most tools, it is not perfect +nor covers every single case, but it is good enough to be helpful. + +``clang-format`` can be used for several purposes: + + - Quickly reformat a block of code to the kernel style. Specially useful + when moving code around and aligning/sorting. See clangformatreformat_. + + - Spot style mistakes, typos and possible improvements in files + you maintain, patches you review, diffs, etc. See clangformatreview_. + + - Help you follow the coding style rules, specially useful for those + new to kernel development or working at the same time in several + projects with different coding styles. + +Its configuration file is ``.clang-format`` in the root of the kernel tree. +The rules contained there try to approximate the most common kernel +coding style. They also try to follow :ref:`Documentation/process/coding-style.rst ` +as much as possible. Since not all the kernel follows the same style, +it is possible that you may want to tweak the defaults for a particular +subsystem or folder. To do so, you can override the defaults by writing +another ``.clang-format`` file in a subfolder. + +The tool itself has already been included in the repositories of popular +Linux distributions for a long time. Search for ``clang-format`` in +your repositories. Otherwise, you can either download pre-built +LLVM/clang binaries or build the source code from: + + https://releases.llvm.org/download.html + +See more information about the tool at: + + https://clang.llvm.org/docs/ClangFormat.html + + https://clang.llvm.org/docs/ClangFormatStyleOptions.html + + +.. _clangformatreview: + +Review files and patches for coding style +----------------------------------------- + +By running the tool in its inline mode, you can review full subsystems, +folders or individual files for code style mistakes, typos or improvements. + +To do so, you can run something like:: + + # Make sure your working directory is clean! + clang-format -i kernel/*.[ch] + +And then take a look at the git diff. + +Counting the lines of such a diff is also useful for improving/tweaking +the style options in the configuration file; as well as testing new +``clang-format`` features/versions. + +``clang-format`` also supports reading unified diffs, so you can review +patches and git diffs easily. See the documentation at: + + https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting + +To avoid ``clang-format`` formatting some portion of a file, you can do:: + + int formatted_code; + // clang-format off + void unformatted_code ; + // clang-format on + void formatted_code_again; + +While it might be tempting to use this to keep a file always in sync with +``clang-format``, specially if you are writing new files or if you are +a maintainer, please note that people might be running different +``clang-format`` versions or not have it available at all. Therefore, +you should probably refrain yourself from using this in kernel sources; +at least until we see if ``clang-format`` becomes commonplace. + + +.. _clangformatreformat: + +Reformatting blocks of code +--------------------------- + +By using an integration with your text editor, you can reformat arbitrary +blocks (selections) of code with a single keystroke. This is specially +useful when moving code around, for complex code that is deeply intended, +for multi-line macros (and aligning their backslashes), etc. + +Remember that you can always tweak the changes afterwards in those cases +where the tool did not do an optimal job. But as a first approximation, +it can be very useful. + +There are integrations for many popular text editors. For some of them, +like vim, emacs, BBEdit and Visual Studio you can find support built-in. +For instructions, read the appropriate section at: + + https://clang.llvm.org/docs/ClangFormat.html + +For Atom, Eclipse, Sublime Text, Visual Studio Code, XCode and other +editors and IDEs you should be able to find ready-to-use plugins. + +For this use case, consider using a secondary ``.clang-format`` +so that you can tweak a few options. See clangformatextra_. + + +.. _clangformatmissing: + +Missing support +--------------- + +``clang-format`` is missing support for some things that are common +in kernel code. They are easy to remember, so if you use the tool +regularly, you will quickly learn to avoid/ignore those. + +In particular, some very common ones you will notice are: + + - Aligned blocks of one-line ``#defines``, e.g.:: + + #define TRACING_MAP_BITS_DEFAULT 11 + #define TRACING_MAP_BITS_MAX 17 + #define TRACING_MAP_BITS_MIN 7 + + vs.:: + + #define TRACING_MAP_BITS_DEFAULT 11 + #define TRACING_MAP_BITS_MAX 17 + #define TRACING_MAP_BITS_MIN 7 + + - Aligned designated initializers, e.g.:: + + static const struct file_operations uprobe_events_ops = { + .owner = THIS_MODULE, + .open = probes_open, + .read = seq_read, + .llseek = seq_lseek, + .release = seq_release, + .write = probes_write, + }; + + vs.:: + + static const struct file_operations uprobe_events_ops = { + .owner = THIS_MODULE, + .open = probes_open, + .read = seq_read, + .llseek = seq_lseek, + .release = seq_release, + .write = probes_write, + }; + + +.. _clangformatextra: + +Extra features/options +---------------------- + +Some features/style options are not enabled by default in the configuration +file in order to minimize the differences between the output and the current +code. In other words, to make the difference as small as possible, +which makes reviewing full-file style, as well diffs and patches as easy +as possible. + +In other cases (e.g. particular subsystems/folders/files), the kernel style +might be different and enabling some of these options may approximate +better the style there. + +For instance: + + - Aligning assignments (``AlignConsecutiveAssignments``). + + - Aligning declarations (``AlignConsecutiveDeclarations``). + + - Reflowing text in comments (``ReflowComments``). + + - Sorting ``#includes`` (``SortIncludes``). + +They are typically useful for block re-formatting, rather than full-file. +You might want to create another ``.clang-format`` file and use that one +from your editor/IDE instead. diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index efa49cdc8e2e..a5f241cf0c02 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -16,6 +16,7 @@ Documentation/dev-tools/testing-overview.rst testing-overview checkpatch + clang-format coccinelle sparse kcov diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index c2046dec0c2f..80bcc1cabc23 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -63,7 +63,7 @@ these rules, to quickly re-format parts of your code automatically, and to review full files in order to spot coding style mistakes, typos and possible improvements. It is also handy for sorting ``#includes``, for aligning variables/macros, for reflowing text and other similar tasks. -See the file :ref:`Documentation/process/clang-format.rst ` +See the file :ref:`Documentation/dev-tools/clang-format.rst ` for more details. Some basic editor settings, such as indentation and line endings, will be diff --git a/Documentation/process/clang-format.rst b/Documentation/process/clang-format.rst deleted file mode 100644 index 1d089a847c1b..000000000000 --- a/Documentation/process/clang-format.rst +++ /dev/null @@ -1,184 +0,0 @@ -.. _clangformat: - -clang-format -============ - -``clang-format`` is a tool to format C/C++/... code according to -a set of rules and heuristics. Like most tools, it is not perfect -nor covers every single case, but it is good enough to be helpful. - -``clang-format`` can be used for several purposes: - - - Quickly reformat a block of code to the kernel style. Specially useful - when moving code around and aligning/sorting. See clangformatreformat_. - - - Spot style mistakes, typos and possible improvements in files - you maintain, patches you review, diffs, etc. See clangformatreview_. - - - Help you follow the coding style rules, specially useful for those - new to kernel development or working at the same time in several - projects with different coding styles. - -Its configuration file is ``.clang-format`` in the root of the kernel tree. -The rules contained there try to approximate the most common kernel -coding style. They also try to follow :ref:`Documentation/process/coding-style.rst ` -as much as possible. Since not all the kernel follows the same style, -it is possible that you may want to tweak the defaults for a particular -subsystem or folder. To do so, you can override the defaults by writing -another ``.clang-format`` file in a subfolder. - -The tool itself has already been included in the repositories of popular -Linux distributions for a long time. Search for ``clang-format`` in -your repositories. Otherwise, you can either download pre-built -LLVM/clang binaries or build the source code from: - - https://releases.llvm.org/download.html - -See more information about the tool at: - - https://clang.llvm.org/docs/ClangFormat.html - - https://clang.llvm.org/docs/ClangFormatStyleOptions.html - - -.. _clangformatreview: - -Review files and patches for coding style ------------------------------------------ - -By running the tool in its inline mode, you can review full subsystems, -folders or individual files for code style mistakes, typos or improvements. - -To do so, you can run something like:: - - # Make sure your working directory is clean! - clang-format -i kernel/*.[ch] - -And then take a look at the git diff. - -Counting the lines of such a diff is also useful for improving/tweaking -the style options in the configuration file; as well as testing new -``clang-format`` features/versions. - -``clang-format`` also supports reading unified diffs, so you can review -patches and git diffs easily. See the documentation at: - - https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting - -To avoid ``clang-format`` formatting some portion of a file, you can do:: - - int formatted_code; - // clang-format off - void unformatted_code ; - // clang-format on - void formatted_code_again; - -While it might be tempting to use this to keep a file always in sync with -``clang-format``, specially if you are writing new files or if you are -a maintainer, please note that people might be running different -``clang-format`` versions or not have it available at all. Therefore, -you should probably refrain yourself from using this in kernel sources; -at least until we see if ``clang-format`` becomes commonplace. - - -.. _clangformatreformat: - -Reformatting blocks of code ---------------------------- - -By using an integration with your text editor, you can reformat arbitrary -blocks (selections) of code with a single keystroke. This is specially -useful when moving code around, for complex code that is deeply intended, -for multi-line macros (and aligning their backslashes), etc. - -Remember that you can always tweak the changes afterwards in those cases -where the tool did not do an optimal job. But as a first approximation, -it can be very useful. - -There are integrations for many popular text editors. For some of them, -like vim, emacs, BBEdit and Visual Studio you can find support built-in. -For instructions, read the appropriate section at: - - https://clang.llvm.org/docs/ClangFormat.html - -For Atom, Eclipse, Sublime Text, Visual Studio Code, XCode and other -editors and IDEs you should be able to find ready-to-use plugins. - -For this use case, consider using a secondary ``.clang-format`` -so that you can tweak a few options. See clangformatextra_. - - -.. _clangformatmissing: - -Missing support ---------------- - -``clang-format`` is missing support for some things that are common -in kernel code. They are easy to remember, so if you use the tool -regularly, you will quickly learn to avoid/ignore those. - -In particular, some very common ones you will notice are: - - - Aligned blocks of one-line ``#defines``, e.g.:: - - #define TRACING_MAP_BITS_DEFAULT 11 - #define TRACING_MAP_BITS_MAX 17 - #define TRACING_MAP_BITS_MIN 7 - - vs.:: - - #define TRACING_MAP_BITS_DEFAULT 11 - #define TRACING_MAP_BITS_MAX 17 - #define TRACING_MAP_BITS_MIN 7 - - - Aligned designated initializers, e.g.:: - - static const struct file_operations uprobe_events_ops = { - .owner = THIS_MODULE, - .open = probes_open, - .read = seq_read, - .llseek = seq_lseek, - .release = seq_release, - .write = probes_write, - }; - - vs.:: - - static const struct file_operations uprobe_events_ops = { - .owner = THIS_MODULE, - .open = probes_open, - .read = seq_read, - .llseek = seq_lseek, - .release = seq_release, - .write = probes_write, - }; - - -.. _clangformatextra: - -Extra features/options ----------------------- - -Some features/style options are not enabled by default in the configuration -file in order to minimize the differences between the output and the current -code. In other words, to make the difference as small as possible, -which makes reviewing full-file style, as well diffs and patches as easy -as possible. - -In other cases (e.g. particular subsystems/folders/files), the kernel style -might be different and enabling some of these options may approximate -better the style there. - -For instance: - - - Aligning assignments (``AlignConsecutiveAssignments``). - - - Aligning declarations (``AlignConsecutiveDeclarations``). - - - Reflowing text in comments (``ReflowComments``). - - - Sorting ``#includes`` (``SortIncludes``). - -They are typically useful for block re-formatting, rather than full-file. -You might want to create another ``.clang-format`` file and use that one -from your editor/IDE instead. diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 7e768c65aa92..04f6aa377a5d 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -732,7 +732,7 @@ these rules, to quickly re-format parts of your code automatically, and to review full files in order to spot coding style mistakes, typos and possible improvements. It is also handy for sorting ``#includes``, for aligning variables/macros, for reflowing text and other similar tasks. -See the file :ref:`Documentation/process/clang-format.rst ` +See the file :ref:`Documentation/dev-tools/clang-format.rst ` for more details. Some basic editor settings, such as indentation and line endings, will be diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index fb089bf9d6a8..1827e73f6376 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -113,7 +113,6 @@ lack of a better place. .. toctree:: :maxdepth: 1 - clang-format .. only:: subproject and html diff --git a/Documentation/translations/it_IT/process/clang-format.rst b/Documentation/translations/it_IT/process/clang-format.rst index 29f83c198025..6fab07772da0 100644 --- a/Documentation/translations/it_IT/process/clang-format.rst +++ b/Documentation/translations/it_IT/process/clang-format.rst @@ -1,6 +1,6 @@ .. include:: ../disclaimer-ita.rst -:Original: :ref:`Documentation/process/clang-format.rst ` +:Original: :ref:`Documentation/dev-tools/clang-format.rst ` :Translator: Federico Vaga .. _it_clangformat: diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst index b5a84df44cea..025223be9706 100644 --- a/Documentation/translations/sp_SP/process/coding-style.rst +++ b/Documentation/translations/sp_SP/process/coding-style.rst @@ -754,7 +754,7 @@ código automáticamente, y revisar archivos completos para detectar errores de estilo del código, errores tipográficos y posibles mejoras. También es útil para ordenar ``#includes``, para alinear variables/macros, para redistribuir texto y otras tareas similares. Vea el archivo -:ref:`Documentation/process/clang-format.rst ` para más +:ref:`Documentation/dev-tools/clang-format.rst ` para más detalles. 10) Archivos de configuración de Kconfig diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst index 7cac9424f5d5..4cc35d410dbc 100644 --- a/Documentation/translations/zh_CN/process/4.Coding.rst +++ b/Documentation/translations/zh_CN/process/4.Coding.rst @@ -54,7 +54,7 @@ 注意您还可以使用 ``clang-format`` 工具来帮助您处理这些规则，快速自动重新格式 化部分代码，和审阅完整的文件以发现代码样式错误、拼写错误和可能的改进。它还 可以方便地排序 ``#includes`` 、对齐变量/宏、重排文本和其他类似任务。有关详细 -信息，请参阅文档 :ref:`Documentation/process/clang-format.rst ` +信息，请参阅文档 :ref:`Documentation/dev-tools/clang-format.rst ` 抽象层 ****** diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst index 3bc2810b151d..10b9cb4f6a65 100644 --- a/Documentation/translations/zh_CN/process/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -654,7 +654,7 @@ Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。 请注意，您还可以使用 ``clang-format`` 工具帮助您处理这些规则，快速自动重新格 式化部分代码，并审阅整个文件以发现代码风格错误、打字错误和可能的改进。它还可 以方便地排序 ``#include`` ，对齐变量/宏，重排文本和其他类似任务。 -详见 Documentation/process/clang-format.rst 。 +详见 Documentation/dev-tools/clang-format.rst 。 10) Kconfig 配置文件 diff --git a/Documentation/translations/zh_TW/process/4.Coding.rst b/Documentation/translations/zh_TW/process/4.Coding.rst index bdd2abe4daf4..e90a6b51fb98 100644 --- a/Documentation/translations/zh_TW/process/4.Coding.rst +++ b/Documentation/translations/zh_TW/process/4.Coding.rst @@ -57,7 +57,7 @@ 注意您還可以使用 ``clang-format`` 工具來幫助您處理這些規則，快速自動重新格式 化部分代碼，和審閱完整的文件以發現代碼樣式錯誤、拼寫錯誤和可能的改進。它還 可以方便地排序 ``#includes`` 、對齊變量/宏、重排文本和其他類似任務。有關詳細 -信息，請參閱文檔 :ref:`Documentation/process/clang-format.rst ` +信息，請參閱文檔 :ref:`Documentation/dev-tools/clang-format.rst ` 抽象層 ****** diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst index c7ac504f6f40..311c6f6bad0b 100644 --- a/Documentation/translations/zh_TW/process/coding-style.rst +++ b/Documentation/translations/zh_TW/process/coding-style.rst @@ -657,7 +657,7 @@ Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。 請注意，您還可以使用 ``clang-format`` 工具幫助您處理這些規則，快速自動重新格 式化部分代碼，並審閱整個文件以發現代碼風格錯誤、打字錯誤和可能的改進。它還可 以方便地排序 ``#include`` ，對齊變量/宏，重排文本和其他類似任務。 -詳見 Documentation/process/clang-format.rst 。 +詳見 Documentation/dev-tools/clang-format.rst 。 10) Kconfig 配置文件 -- cgit v1.2.3 From ccd46f62196702ee476d46a673883f5bf5779f89 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Mon, 24 Jun 2024 11:53:10 -0700 Subject: Docs/process/index: Remove unsorted docs section 'Other material' section on 'process/index' is no more necessary since we have 'staging/' directory. Also all documents on the section has moved to better places. Remove the section. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240624185312.94537-6-sj@kernel.org --- Documentation/process/index.rst | 7 ------- 1 file changed, 7 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 1827e73f6376..6455eba3ef0c 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -107,13 +107,6 @@ developers: kernel-docs deprecated -These are some overall technical guides that have been put here for now for -lack of a better place. - -.. toctree:: - :maxdepth: 1 - - .. only:: subproject and html Indices -- cgit v1.2.3 From 7fe7de7be8286fddd9204efb248f4768f47ed690 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Mon, 24 Jun 2024 11:53:12 -0700 Subject: Docs/process/email-clients: Document HacKerMaiL HacKerMaiL (hkml) [1] is a simple tool for mailing lists-based development workflows such as that for most Linux kernel subsystems. It is actively being maintained by DAMON maintainer, and recommended for DAMON community[2]. Add a simple introduction of the tool on the email-clients document, too. [1] https://github.com/sjp38/hackermail [2] https://lore.kernel.org/20240621170353.BFB83C2BBFC@smtp.kernel.org Signed-off-by: SeongJae Park Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240624185312.94537-8-sj@kernel.org --- Documentation/process/email-clients.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'Documentation/process') diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst index fc2c46f3f82d..dd22c46d1d02 100644 --- a/Documentation/process/email-clients.rst +++ b/Documentation/process/email-clients.rst @@ -350,3 +350,12 @@ although tab2space problem can be solved with external editor. Another problem is that Gmail will base64-encode any message that has a non-ASCII character. That includes things like European names. + +HacKerMaiL (TUI) +**************** + +HacKerMaiL (hkml) is a public-inbox based simple mails management tool that +doesn't require subscription of mailing lists. It is developed and maintained +by the DAMON maintainer and aims to support simple development workflows for +DAMON and general kernel subsystems. Refer to the README +(https://github.com/sjp38/hackermail/blob/master/README.md) for details. -- cgit v1.2.3 From bbc0611a0fc43b29d5357bab2a7e309bc3202fc8 Mon Sep 17 00:00:00 2001 From: Carlos Bilbao Date: Sat, 22 Jun 2024 14:47:27 -0500 Subject: docs: Extend and refactor index of further kernel docs Extend the Index of Further Kernel Documentation by adding entries for the Rust for Linux website, the Linux Foundation's YouTube channel, and notes on the second edition of Billimoria's kernel programming book. Also, perform some refactoring: format the text to 75 characters per line and sort per-section content in chronological order of publication. Signed-off-by: Carlos Bilbao Tested-by: Randy Dunlap Acked-by: Randy Dunlap Link: https://lore.kernel.org/r/20240622194727.2171845-1-carlos.bilbao.osdev@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/process/kernel-docs.rst | 68 ++++++++++++++++++++++------------- 1 file changed, 44 insertions(+), 24 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index 8660493b91d0..6f3e290abd22 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -3,27 +3,27 @@ Index of Further Kernel Documentation ===================================== -The need for a document like this one became apparent in the -linux-kernel mailing list as the same questions, asking for pointers -to information, appeared again and again. +The need for a document like this one became apparent in the linux-kernel +mailing list as the same questions, asking for pointers to information, +appeared again and again. -Fortunately, as more and more people get to GNU/Linux, more and more -get interested in the Kernel. But reading the sources is not always -enough. It is easy to understand the code, but miss the concepts, the -philosophy and design decisions behind this code. +Fortunately, as more and more people get to GNU/Linux, more and more get +interested in the Kernel. But reading the sources is not always enough. It +is easy to understand the code, but miss the concepts, the philosophy and +design decisions behind this code. -Unfortunately, not many documents are available for beginners to -start. And, even if they exist, there was no "well-known" place which -kept track of them. These lines try to cover this lack. +Unfortunately, not many documents are available for beginners to start. +And, even if they exist, there was no "well-known" place which kept track +of them. These lines try to cover this lack. PLEASE, if you know any paper not listed here or write a new document, include a reference to it here, following the kernel's patch submission process. Any corrections, ideas or comments are also welcome. All documents are cataloged with the following fields: the document's -"Title", the "Author"/s, the "URL" where they can be found, some -"Keywords" helpful when searching for specific topics, and a brief -"Description" of the Document. +"Title", the "Author"/s, the "URL" where they can be found, some "Keywords" +helpful when searching for specific topics, and a brief "Description" of +the Document. .. note:: @@ -72,9 +72,29 @@ On-line docs programming. Lots of examples. Currently the new version is being actively maintained at https://github.com/sysprog21/lkmpg. + * Title: **Rust for Linux** + + :Author: various + :URL: https://rust-for-linux.com/ + :Date: rolling version + :Keywords: glossary, terms, linux-kernel. + :Description: From the website: "Rust for Linux is the project adding + support for the Rust language to the Linux kernel. This website is + intended as a hub of links, documentation and resources related to + the project". + Published books --------------- + * Title: **Practical Linux System Administration: A Guide to Installation, Configuration, and Management, 1st Edition** + + :Author: Kenneth Hess + :Publisher: O'Reilly Media + :Date: May, 2023 + :Pages: 246 + :ISBN: 978-1098109035 + :Notes: System administration + * Title: **Linux Kernel Debugging: Leverage proven tools and advanced techniques to effectively debug Linux kernels and kernel modules** :Author: Kaiwan N Billimoria @@ -88,9 +108,9 @@ Published books :Author: Kaiwan N Billimoria :Publisher: Packt Publishing Ltd - :Date: March, 2021 + :Date: March, 2021 (Second Edition published in 2024) :Pages: 754 - :ISBN: 978-1789953435 + :ISBN: 978-1789953435 (Second Edition ISBN is 978-1803232225) * Title: **Linux Kernel Programming Part 2 - Char Device Drivers and Kernel Synchronization: Create user-kernel interfaces, work with peripheral I/O, and handle hardware interrupts** @@ -118,15 +138,6 @@ Published books :ISBN: 978-0672329463 :Notes: Foundational book - * Title: **Practical Linux System Administration: A Guide to Installation, Configuration, and Management, 1st Edition** - - :Author: Kenneth Hess - :Publisher: O'Reilly Media - :Date: May, 2023 - :Pages: 246 - :ISBN: 978-1098109035 - :Notes: System administration - .. _ldd3_published: * Title: **Linux Device Drivers, 3rd Edition** @@ -201,6 +212,15 @@ Miscellaneous :Description: Some of the linux-kernel mailing list archivers. If you have a better/another one, please let me know. + * Name: **The Linux Foundation YouTube channel** + + :URL: https://www.youtube.com/user/thelinuxfoundation + :Keywords: linux, videos, linux-foundation, youtube. + :Description: The Linux Foundation uploads video recordings of their + collaborative events, Linux conferences including LinuxCon, and + other original research and content related to Linux and software + development. + ------- This document was originally based on: -- cgit v1.2.3 From 413e775efaec9b4525480be570cae46406dd759d Mon Sep 17 00:00:00 2001 From: Konstantin Ryabitsev Date: Wed, 19 Jun 2024 14:24:06 -0400 Subject: Documentation: fix links to mailing list services There have been some changes to the way mailing lists are hosted at kernel.org. This patch does the following: 1. fixes links that are pointing at the outdated resources 2. removes an outdated patchbomb admonition We still don't particularly want or welcome huge patchbombs, but they are less likely to overload our systems. Acked-by: Dan Williams Signed-off-by: Konstantin Ryabitsev Reviewed-by: Carlos Bilbao Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240619-docs-patch-msgid-link-v2-1-72dd272bfe37@linuxfoundation.org --- Documentation/process/2.Process.rst | 8 ++++---- Documentation/process/howto.rst | 10 +++++----- Documentation/process/kernel-docs.rst | 5 ++--- Documentation/process/maintainer-netdev.rst | 5 ++--- Documentation/process/submitting-patches.rst | 15 +++++---------- 5 files changed, 18 insertions(+), 25 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst index 613a01da4717..ef3b116492df 100644 --- a/Documentation/process/2.Process.rst +++ b/Documentation/process/2.Process.rst @@ -392,13 +392,13 @@ represent a potential hazard to developers, who risk getting buried under a load of electronic mail, running afoul of the conventions used on the Linux lists, or both. -Most kernel mailing lists are run on vger.kernel.org; the master list can +Most kernel mailing lists are hosted at kernel.org; the master list can be found at: - http://vger.kernel.org/vger-lists.html + https://subspace.kernel.org -There are lists hosted elsewhere, though; a number of them are at -redhat.com/mailman/listinfo. +There are lists hosted elsewhere; please check the MAINTAINERS file for +the list relevant for any particular subsystem. The core mailing list for kernel development is, of course, linux-kernel. This list is an intimidating place to be; volume can reach 500 messages per diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index eebda4910a88..9438e03d6f50 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -331,7 +331,7 @@ they need to be integration-tested. For this purpose, a special testing repository exists into which virtually all subsystem trees are pulled on an almost daily basis: - https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git + https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git This way, the linux-next gives a summary outlook onto what will be expected to go into the mainline kernel at the next merge period. @@ -373,12 +373,12 @@ As some of the above documents describe, the majority of the core kernel developers participate on the Linux Kernel Mailing list. Details on how to subscribe and unsubscribe from the list can be found at: - http://vger.kernel.org/vger-lists.html#linux-kernel + https://subspace.kernel.org/subscribing.html There are archives of the mailing list on the web in many different places. Use a search engine to find these archives. For example: - https://lore.kernel.org/lkml/ + https://lore.kernel.org/linux-kernel/ It is highly recommended that you search the archives about the topic you want to bring up, before you post it to the list. A lot of things @@ -393,13 +393,13 @@ groups. Many of the lists are hosted on kernel.org. Information on them can be found at: - http://vger.kernel.org/vger-lists.html + https://subspace.kernel.org Please remember to follow good behavioral habits when using the lists. Though a bit cheesy, the following URL has some simple guidelines for interacting with the list (or any list): - http://www.albion.com/netiquette/ + https://subspace.kernel.org/etiquette.html If multiple people respond to your mail, the CC: list of recipients may get pretty large. Don't remove anybody from the CC: list without a good diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index 6f3e290abd22..55552ec4b043 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -205,9 +205,8 @@ Miscellaneous * Name: **linux-kernel mailing list archives and search engines** - :URL: http://vger.kernel.org/vger-lists.html - :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html - :URL: http://groups.google.com/group/mlist.linux.kernel + :URL: https://subspace.kernel.org + :URL: https://lore.kernel.org :Keywords: linux-kernel, archives, search. :Description: Some of the linux-kernel mailing list archivers. If you have a better/another one, please let me know. diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst index fd96e4a3cef9..da12a7554d49 100644 --- a/Documentation/process/maintainer-netdev.rst +++ b/Documentation/process/maintainer-netdev.rst @@ -25,9 +25,8 @@ drivers/net (i.e. hardware specific drivers) in the Linux source tree. Note that some subsystems (e.g. wireless drivers) which have a high volume of traffic have their own specific mailing lists and trees. -The netdev list is managed (like many other Linux mailing lists) through -VGER (http://vger.kernel.org/) with archives available at -https://lore.kernel.org/netdev/ +Like many other Linux mailing lists, the netdev list is hosted at +kernel.org with archives available at https://lore.kernel.org/netdev/. Aside from subsystems like those mentioned above, all network-related Linux development (i.e. RFC, review, comments, etc.) takes place on diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 66029999b587..f310f2f36666 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -119,10 +119,10 @@ web, point to it. When linking to mailing list archives, preferably use the lore.kernel.org message archiver service. To create the link URL, use the contents of the -``Message-Id`` header of the message without the surrounding angle brackets. +``Message-ID`` header of the message without the surrounding angle brackets. For example:: - Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI Please check the link to make sure that it is actually working and points to the relevant message. @@ -243,11 +243,9 @@ linux-kernel@vger.kernel.org should be used by default for all patches, but the volume on that list has caused a number of developers to tune it out. Please do not spam unrelated lists and unrelated people, though. -Many kernel-related lists are hosted on vger.kernel.org; you can find a -list of them at http://vger.kernel.org/vger-lists.html. There are -kernel-related lists hosted elsewhere as well, though. - -Do not send more than 15 patches at once to the vger mailing lists!!! +Many kernel-related lists are hosted at kernel.org; you can find a list +of them at https://subspace.kernel.org. There are kernel-related lists +hosted elsewhere as well, though. Linus Torvalds is the final arbiter of all changes accepted into the Linux kernel. His e-mail address is . @@ -866,9 +864,6 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". -NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! - - Kernel Documentation/process/coding-style.rst Linus Torvalds's mail on the canonical patch format: -- cgit v1.2.3 From 127734e23aed3746d7dd14c7070ea3f2d634912d Mon Sep 17 00:00:00 2001 From: Konstantin Ryabitsev Date: Wed, 19 Jun 2024 14:24:07 -0400 Subject: Documentation: best practices for using Link trailers Based on multiple conversations, most recently on the ksummit mailing list [1], add some best practices for using the Link trailer, such as: - how to use markdown-like bracketed numbers in the commit message to indicate the corresponding link - when to use lore.kernel.org vs patch.msgid.link domains Cc: ksummit@lists.linux.dev Link: https://lore.kernel.org/20240617-arboreal-industrious-hedgehog-5b84ae@meerkat # [1] Signed-off-by: Konstantin Ryabitsev Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240619-docs-patch-msgid-link-v2-2-72dd272bfe37@linuxfoundation.org --- Documentation/process/maintainer-tip.rst | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst index 64739968afa6..ba312345d030 100644 --- a/Documentation/process/maintainer-tip.rst +++ b/Documentation/process/maintainer-tip.rst @@ -372,17 +372,31 @@ following tag ordering scheme: - Link: ``https://link/to/information`` - For referring to an email on LKML or other kernel mailing lists, - please use the lore.kernel.org redirector URL:: + For referring to an email posted to the kernel mailing lists, please + use the lore.kernel.org redirector URL:: - https://lore.kernel.org/r/email-message@id + Link: https://lore.kernel.org/email-message-id@here - The kernel.org redirector is considered a stable URL, unlike other email - archives. + This URL should be used when referring to relevant mailing list + topics, related patch sets, or other notable discussion threads. + A convenient way to associate ``Link:`` trailers with the commit + message is to use markdown-like bracketed notation, for example:: - Maintainers will add a Link tag referencing the email of the patch - submission when they apply a patch to the tip tree. This tag is useful - for later reference and is also used for commit notifications. + A similar approach was attempted before as part of a different + effort [1], but the initial implementation caused too many + regressions [2], so it was backed out and reimplemented. + + Link: https://lore.kernel.org/some-msgid@here # [1] + Link: https://bugzilla.example.org/bug/12345 # [2] + + You can also use ``Link:`` trailers to indicate the origin of the + patch when applying it to your git tree. In that case, please use the + dedicated ``patch.msgid.link`` domain instead of ``lore.kernel.org``. + This practice makes it possible for automated tooling to identify + which link to use to retrieve the original patch submission. For + example:: + + Link: https://patch.msgid.link/patch-source-message-id@here Please do not use combined tags, e.g. ``Reported-and-tested-by``, as they just complicate automated extraction of tags. -- cgit v1.2.3