aboutsummaryrefslogtreecommitdiffstats
AgeCommit message (Collapse)AuthorFilesLines
2022-03-30docs: Add a document on how to fix a messy diffstatJonathan Corbet2-0/+97
A branch with merges in will sometimes create a diffstat containing a lot of unrelated work at "git request-pull" time. Create a document based on Linus's advice (found in the links below) and add it to the maintainer manual in the hope of saving some wear on Linus's keyboard going forward. Link: https://lore.kernel.org/lkml/CAHk-=wg3wXH2JNxkQi+eLZkpuxqV+wPiHhw_Jf7ViH33Sw7PHA@mail.gmail.com/ Link: https://lore.kernel.org/lkml/CAHk-=wgXbSa8yq8Dht8at+gxb_idnJ7X5qWZQWRBN4_CUPr=eQ@mail.gmail.com/ Acked-by: Borislav Petkov <bp@suse.de> Reviewed-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-30docs: sphinx/requirements: Limit jinja2<3.1Akira Yokosawa1-0/+2
jinja2 release 3.1.0 (March 24, 2022) broke Sphinx<4.0. This looks like the result of deprecating Python 3.6. It has been tested against Sphinx 4.3.0 and later. Setting an upper limit of <3.1 to junja2 can unbreak Sphinx<4.0 including Sphinx 2.4.4. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: stable@vger.kernel.org # v5.15+ Link: https://lore.kernel.org/r/7dbff8a0-f4ff-34a0-71c7-1987baf471f9@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-28Documentation: kunit: Fix cross-referencing warningsDavid Gow1-11/+2
The Architecture chapter of the KUnit documentation tried to include copies of the kernel-doc for a couple of things, despite these already existing in the API documentation. This lead to some warnings: architecture:31: ./include/kunit/test.h:3: WARNING: Duplicate C declaration, also defined at dev-tools/kunit/api/test:66. Declaration is '.. c:struct:: kunit_case'. architecture:163: ./include/kunit/test.h:1217: WARNING: Duplicate C declaration, also defined at dev-tools/kunit/api/test:1217. Declaration is '.. c:macro:: KUNIT_ARRAY_PARAM'. architecture.rst:3: WARNING: Duplicate C declaration, also defined at dev-tools/kunit/api/test:66. Declaration is '.. c:struct:: kunit_case'. architecture.rst:1217: WARNING: Duplicate C declaration, also defined at dev-tools/kunit/api/test:1217. Declaration is '.. c:macro:: KUNIT_ARRAY_PARAM'. Get rid of these, and cleanup the mentions of the struct and macro in question so that sphinx generates a link to the existing copy of the documentation in the api/test document. Fixes: bc145b370c11 ("Documentation: KUnit: Added KUnit Architecture") Signed-off-by: David Gow <davidgow@google.com> Reviewed-by: Brendan Higgins <brendanhiggins@google.com> Tested-by: Brendan Higgins <brendanhiggins@google.com> Link: https://lore.kernel.org/r/20220326054414.637293-1-davidgow@google.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-28scripts/kernel-doc: change the line number meta infoMauro Carvalho Chehab2-3/+3
In order to make it more standard and ReST compatible, change the meta-tag used with --enable-lineno from: #define LINENO to .. LINENO In practice, no functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/40725032b5a4a33db740bf1de397523af958ff8a.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-28scripts/get_abi: change the file/line number meta infoMauro Carvalho Chehab2-3/+3
In order to make it more standard and ReST compatible, change the meta-tag used with --enable-lineno from: #define LINENO to .. LINENO In practice, no functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/125ffd31fbc77ad9eee4d6906e1830b8162fa6ca.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-28docs: kernel_include.py: add sphinx build dependenciesMauro Carvalho Chehab1-0/+3
The files included by kernel-include should be added as build dependencies, in order for sphinx-build to rebuild the corresponding docs if any changes at the included file happens. Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/d30fc4fa422a13b7e1623d690945c46b58a55e79.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-28docs: kernel_abi.py: add sphinx build dependenciesMauro Carvalho Chehab1-0/+4
Ensure that Sphinx-build will handle the files parsed by get_abi.pl as dependencies. This way, if they are touched, the ABI output will be regenerated. Reported-by: Hans de Goede <hdegoede@redhat.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/10bc3d3bc74f514a539cd3b48b9d287d2b6f99e2.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-28docs: kernel_feat.py: add build dependenciesMauro Carvalho Chehab1-2/+18
Ensure that the feature files will be regenerated if any changes happen at the Documentation/features files that were processed by gen_feat.pl. Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/5cdf7a8300019129dcc09d4c2557f75908754445.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-28scripts/get_feat.pl: allow output the parsed file namesMauro Carvalho Chehab1-0/+11
Such output could be helpful while debugging it, but its main goal is to tell kernel_feat.py about what files were used by the script. Thie way, kernel_feat.py can add those as documentation dependencies. Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/11b438ee01e00c866f5ea197d6aecc26e9f86945.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-28docs: kfigure.py: Don't warn of missing PDF converter in 'make htmldocs'Akira Yokosawa1-3/+5
SVG -> PDF conversion is not required in "make htmldocs". It is pointless to always warn of a missing converter. Demote the log message in setupTools() to verbose. For "make pdfdocs" (or "make latexdocs"), promote the dynamic message of "include SVG raw" to a warn. Expand the message and recommend installing Inkscape or ImageMagick. Fixes: 8ccd05697a9d ("docs: sphinx/kfigure.py: Use inkscape(1) for SVG -> PDF conversion") Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: linux-doc@vger.kernel.org Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/c80e1481-10d4-7151-fe59-e846259eb0d4@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-25Documentation: Fix duplicate statement about raw_spinlock_t typeGuilherme G. Piccoli1-3/+0
Unless it was duplicate on purpose, to emphasize that a raw_spinlock_t is always a spinning lock regardless of PREEMPT_RT or kernel config, it's a bit odd that this text is duplicate. So, this patch just clean it up, keeping the consistency with the other sections of the text. Cc: Thomas Gleixner <tglx@linutronix.de> Fixes: 919e9e6395cf ("Documentation: Add lock ordering and nesting documentation") Signed-off-by: Guilherme G. Piccoli <gpiccoli@igalia.com> Link: https://lore.kernel.org/r/20220321144133.49804-1-gpiccoli@igalia.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-16docs/kernel-parameters: update description of mem=Mike Rapoport1-0/+18
The existing description of mem= does not cover all the cases and differences between how architectures treat it. Extend the description to match the code. Signed-off-by: Mike Rapoport <rppt@linux.ibm.com> Link: https://lore.kernel.org/r/20220310082736.1346366-1-rppt@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-16docs/zh_CN: Add sched-nice-design Chinese translationTang Yizhou2-1/+100
Translate scheduler/sched-nice-design.rst into Chinese. Signed-off-by: Tang Yizhou <tangyizhou@huawei.com> Reviewed-by: Yanteng Si <siyanteng@loongson.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Link: https://lore.kernel.org/r/20220312072642.23118-1-tangyizhou@huawei.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-16docs: scheduler: Convert schedutil.txt to ReSTTang Yizhou2-13/+18
All other scheduler documents have been converted to *.rst. Let's do the same for schedutil.txt. Also fixed some typos. Signed-off-by: Tang Yizhou <tangyizhou@huawei.com> Link: https://lore.kernel.org/r/20220312070751.16844-1-tangyizhou@huawei.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-11Docs: ktap: add code-block typeRandy Dunlap1-9/+9
Fix multiple "code-block::" warnings by adding "none" as the type of code-block. Mends these warnings: Documentation/dev-tools/ktap.rst:71: WARNING: Error in "code-block" directive: 1 argument(s) required, 0 supplied. Documentation/dev-tools/ktap.rst:120: WARNING: Error in "code-block" directive: 1 argument(s) required, 0 supplied. Documentation/dev-tools/ktap.rst:126: WARNING: Error in "code-block" directive: 1 argument(s) required, 0 supplied. Documentation/dev-tools/ktap.rst:132: WARNING: Error in "code-block" directive: 1 argument(s) required, 0 supplied. Documentation/dev-tools/ktap.rst:139: WARNING: Error in "code-block" directive: 1 argument(s) required, 0 supplied. Documentation/dev-tools/ktap.rst:145: WARNING: Error in "code-block" directive: 1 argument(s) required, 0 supplied. Documentation/dev-tools/ktap.rst:195: WARNING: Error in "code-block" directive: 1 argument(s) required, 0 supplied. Documentation/dev-tools/ktap.rst:208: WARNING: Error in "code-block" directive: 1 argument(s) required, 0 supplied. Documentation/dev-tools/ktap.rst:238: WARNING: Error in "code-block" directive: 1 argument(s) required, 0 supplied. Fixes: a32fa6b2e8b4 ("Documentation: dev-tools: Add KTAP specification") Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: Rae Moar <rmoar@google.com> Cc: David Gow <davidgow@google.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Reviewed-by: Frank Rowand <frank.rowand@sony.com> Reviewed-by: David Gow <davidgow@google.com> Link: https://lore.kernel.org/r/20220131003637.14274-1-rdunlap@infradead.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-11docs: serial: fix a reference file name in driver.rstWan Jiabing1-1/+1
Fix the following 'make refcheckdocs' warning: Warning: Documentation/driver-api/serial/driver.rst references a file that doesn't exist: Documentation/driver-api/serial/tty.rst Signed-off-by: Wan Jiabing <wanjiabing@vivo.com> Reviewed-by: Jiri Slaby <jirislaby@kernel.org> Link: https://lore.kernel.org/r/20220304100315.6732-1-wanjiabing@vivo.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-11docs: UML: Mention telnetd for port channelVincent Whitchurch1-1/+5
It is not obvious from the documentation that using the "port" channel for the console requires telnetd to be installed (see port_connection() in arch/um/drivers/port_user.c). Mention this, and the fact that UML will not boot until a client connects. Signed-off-by: Vincent Whitchurch <vincent.whitchurch@axis.com> Acked-by: Anton Ivanov <anton.ivanov@cambridgegreys.com> Link: https://lore.kernel.org/r/20220310124230.3069354-1-vincent.whitchurch@axis.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-11docs/zh_CN: add damon reclaim translationYanteng Si2-2/+234
Translate .../admin-guide/mm/damon/reclaim.rst into Chinese. Signed-off-by: Yanteng Si <siyanteng@loongson.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Link: https://lore.kernel.org/r/0a436fa78814bb0a7b9c2f3049e544b1e1802560.1646899089.git.siyanteng@loongson.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-11docs/zh_CN: add damon usage translationYanteng Si2-1/+287
Translate .../admin-guide/mm/damon/usage.rst into Chinese. Signed-off-by: Yanteng Si <siyanteng@loongson.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Link: https://lore.kernel.org/r/431f1c2a158c61a6556f58048cb54961ab7a8790.1646899089.git.siyanteng@loongson.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-11docs/zh_CN: add admin-guide damon start translationYanteng Si2-1/+135
Translate Documentation/admin-guide/mm/damon/start.rst into Chinese. Signed-off-by: Yanteng Si <siyanteng@loongson.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Link: https://lore.kernel.org/r/e6e328be018cbf5f9105adfdad56c951acbb8c8f.1646899089.git.siyanteng@loongson.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-11docs/zh_CN: add admin-guide damon index translationYanteng Si2-1/+27
Translate .../admin-guide/mm/damon/index.rst into Chinese. Signed-off-by: Yanteng Si <siyanteng@loongson.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Link: https://lore.kernel.org/r/0251f09dc926972068329b87b0563dd432849497.1646899089.git.siyanteng@loongson.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-11docs/zh_CN: Refactoring the admin-guide directory indexYanteng Si1-61/+61
The Todolist in the html document looks a mess, now give it a nice looking format. Signed-off-by: Yanteng Si <siyanteng@loongson.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Link: https://lore.kernel.org/r/d410408ec13d6e9cff97da50a13d793a428e05cf.1646899089.git.siyanteng@loongson.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-11zh_CN: Add translation for admin-guide/mm/index.rstxu xin2-1/+50
Translate Documentation/admin-guide/mm/index.rst into Chinese. Update Documentation/admin-guide/index.rst. Reviewed-by: Yang Yang <yang.yang29@zte.com.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Reviewed-by: Yanteng Si <siyanteng@loongson.cn> Signed-off-by: xu xin <xu.xin16@zte.com.cn> Signed-off-by: Yanteng Si <siyanteng@loongson.cn> Link: https://lore.kernel.org/r/2d695dac05efc012b99fbc7525be65a421c7de03.1646899056.git.siyanteng@loongson.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-11zh_CN: Add translations for admin-guide/mm/ksm.rstxu xin1-0/+148
Translate Documentation/admin-guide/mm/ksm.rst into Chinese. Reviewed-by: Yang Yang <yang.yang29@zte.com.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Reviewed-by: Yanteng Si <siyanteng@loongson.cn> Signed-off-by: xu xin <xu.xin16@zte.com.cn> Signed-off-by: Yanteng Si <siyanteng@loongson.cn> Link: https://lore.kernel.org/r/f987a3a2cbffaad64f6e2377a5e393d9afbb099c.1646899056.git.siyanteng@loongson.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-11Add Chinese translation for vm/ksm.rstxu xin2-0/+71
Translate Documentation/vm/ksm.rst into Chinese. Update Documentation/translations/zh_CN/vm/index.rst. Reviewed-by: Yang Yang <yang.yang29@zte.com.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Reviewed-by: Yanteng Si <siyanteng@loongson.cn> Signed-off-by: xu xin <xu.xin16@zte.com.cn> Signed-off-by: Yanteng Si <siyanteng@loongson.cn> Link: https://lore.kernel.org/r/ceb82d6458cd79bc3b7060199db0c3518adc3b8b.1646899056.git.siyanteng@loongson.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-09docs/zh_CN: Add sched-stats Chinese translationTang Yizhou2-2/+157
Translate scheduler/sched-stats.rst into Chinese. Signed-off-by: Tang Yizhou <tangyizhou@huawei.com> Reviewed-by: Yanteng Si <siyanteng@loongson.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Link: https://lore.kernel.org/r/20220309153659.24437-1-tangyizhou@huawei.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-09docs/zh_CN: add devicetree of_unittest translationYanteng Si2-2/+190
Translate .../Devicetree/of_unittest.rst into Chinese. Signed-off-by: Yanteng Si <siyanteng@loongson.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Link: https://lore.kernel.org/r/da75225df2ac7bee8de653d95b2a872510b34f7d.1646642188.git.siyanteng@loongson.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-09docs/zh_CN: add devicetree usage-model translationYanteng Si2-1/+333
Translate .../Devicetree/usage-model.rst into Chinese. Signed-off-by: Yanteng Si <siyanteng@loongson.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Link: https://lore.kernel.org/r/abc4bfa5a8eb438013913bf8ea5f8a29e5730f33.1646642188.git.siyanteng@loongson.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-09docs/zh_CN: add devicetree index translationYanteng Si2-1/+54
Translate .../devicetree/index.rst into Chinese. Signed-off-by: Yanteng Si <siyanteng@loongson.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Link: https://lore.kernel.org/r/0a01f2eee980da02c0810d3d99b95af9013b646f.1646642188.git.siyanteng@loongson.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-09Documentation: describe how to apply incremental stable patchesBagas Sanjaya1-5/+23
The applying patches document (Documentation/process/applying-patches.rst) mentions incremental stable patches, but there is no example of how to apply them. Describe the process. While at it, remove note about incremental patches and move the external link of 5.x.y incremental patches to "Where can I download patches?" section. Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Link: https://lore.kernel.org/r/20220307063340.256671-1-bagasdotme@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-09docs/zh_CN: add peci subsystem translationYanteng Si2-2/+56
Translate .../peci/peci.rst into Chinese. Signed-off-by: Yanteng Si <siyanteng@loongson.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Link: https://lore.kernel.org/r/00577790cb16375e0016513e03d06b671006a3da.1646108017.git.siyanteng@loongson.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-09docs/zh_CN: add peci index translationYanteng Si2-0/+27
Translate .../pici/index.rst into Chinese Signed-off-by: Yanteng Si <siyanteng@loongson.cn> Link: https://lore.kernel.org/r/9fdba94417277ae20db7e3b13418584c652be93f.1646108017.git.siyanteng@loongson.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-09docs/zh_CN: add riscv vm-layout translationYanteng Si2-0/+68
Translate .../riscv/vm-layout.rst into Chinese. Signed-off-by: Yanteng Si <siyanteng@loongson.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Link: https://lore.kernel.org/r/b59965f7f88ea22ec824dc2e92561b018fd370d1.1646108017.git.siyanteng@loongson.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-09Documentation/process: Add Researcher GuidelinesKees Cook2-0/+144
As a follow-up to the UMN incident[1], the TAB took the responsibility to document Researcher Guidelines so there would be a common place to point for describing our expectations as a developer community. Document best practices researchers should follow to participate successfully with the Linux developer community. [1] https://lore.kernel.org/lkml/202105051005.49BFABCE@keescook/ Co-developed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Co-developed-by: Jonathan Corbet <corbet@lwn.net> Co-developed-by: Stefano Zacchiroli <zack@upsilon.cc> Signed-off-by: Stefano Zacchiroli <zack@upsilon.cc> Co-developed-by: Steven Rostedt <rostedt@goodmis.org> Signed-off-by: Steven Rostedt <rostedt@goodmis.org> Acked-by: Steve Rostedt <rostedt@goodmis.org> Acked-by: Laura Abbott <labbott@kernel.org> Reviewed-by: Julia Lawall <julia.lawall@inria.fr> Reviewed-by: Wenwen Wang <wenwen@cs.uga.edu> Signed-off-by: Kees Cook <keescook@chromium.org> Link: https://lore.kernel.org/r/20220304181418.1692016-1-keescook@chromium.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-04docs: fix 'make htmldocs' warning in perfWan Jiabing1-0/+1
Fix following 'make htmldocs' warnings: ./Documentation/admin-guide/perf/hisi-pcie-pmu.rst: WARNING: document isn't included in any toctree Fixes: c8602008e247 ("docs: perf: Add description for HiSilicon PCIe PMU driver") Signed-off-by: Wan Jiabing <wanjiabing@vivo.com> Reviewed-by: John Garry <john.garry@huawei.com> Link: https://lore.kernel.org/r/20220228031700.1669086-1-wanjiabing@vivo.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-04Documentation/locking/locktypes: Fix PREEMPT_RT _bh() descriptionAndrew Halaney1-1/+1
With PREEMPT_RT the _bh() version of a spinlock leaves preemption enabled, align the doc to say that instead of the opposite. Reported-by: Leah Leshchinsky <lleshchi@redhat.com> Signed-off-by: Andrew Halaney <ahalaney@redhat.com> Reviewed-by: Boqun Feng <boqun.feng@gmail.com> Link: https://lore.kernel.org/r/20220224212312.2601153-1-ahalaney@redhat.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24docs: reporting-issues.rst: link new document about regressionsThorsten Leemhuis1-37/+36
Make Documentation/admin-guide/reporting-issues.rst point to the newly created document about regressions (Documentation/admin-guide/regressions-regressions.rst). This allows to shorten a few explanations the new document describes better and in more detail. While at it move the copyright hint to the end of the file and remove quotes around links to other places in the documentation. Both issues came up during the review of the new documents about regressions. Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info> Link: https://lore.kernel.org/r/f20114eaddc356a8c79dd62812a6c7f4ca5d87b9.1644994117.git.linux@leemhuis.info Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24docs: *-regressions.rst: explain how quickly issues should be handledThorsten Leemhuis2-0/+99
Add a section with a few rules of thumb about how quickly developers should address regressions to Documentation/process/handling-regressions.rst; additionally, add a short paragraph about this to the companion document Documentation/admin-guide/reporting-regressions.rst as well. The rules of thumb were written after studying the quotes from Linus found in handling-regressions.rst and especially influenced by statements like "Users are literally the _only_ thing that matters" and "without users, your program is not a program, it's a pointless piece of code that you might as well throw away". The author interpreted those in perspective to how the various Linux kernel series are maintained currently and what those practices might mean for users running into a regression on a small or big kernel update. That for example lead to the paragraph starting with "Aim to get fixes for regressions mainlined within one week after identifying the culprit, if the regression was introduced in a stable/longterm release or the devel cycle for the latest mainline release". Some might see this as pretty high bar, but on the other hand something like that is needed to not leave users out in the cold for too long -- which can quickly happen when updating to the latest stable series, as the previous one is normally stamped "End of Life" about three or four weeks after a new mainline release. This makes a lot of users switch during this timeframe. Any of them thus risk running into regressions not promptly fixed; even worse, once the previous stable series is EOLed for real, users that face a regression might be left with only three options: (1) continue running an outdated and thus potentially insecure kernel version from an abandoned stable series (2) run the kernel with the regression (3) downgrade to an earlier longterm series still supported This is better avoided, as (1) puts users and their data in danger, (2) will only be possible if it's a minor regression that doesn't interfere with booting or serious usage, and (3) might be regression itself or impossible on the particular machine, as the users might require drivers or features only introduced after the latest longterm series branched of. In the end this lead to the aforementioned "Aim to fix regression within one week" part. It's also the reason for the "Try to resolve any regressions introduced in the current development cycle before its end.". Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info> CC: Linus Torvalds <torvalds@linux-foundation.org> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Reviewed-by: Lukas Bulwahn <lukas.bulwahn@gmail.com> Link: https://lore.kernel.org/r/a7b717b52c0d54cdec9b6daf56ed6669feddee2c.1644994117.git.linux@leemhuis.info Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24docs: add two documents about regression handlingThorsten Leemhuis5-0/+1102
Create two documents explaining various aspects around regression handling and tracking; one is aimed at users, the other targets developers. The texts among others describes the first rule of Linux kernel development and what it means in practice. They also explain what a regression actually is and how to report one properly. Both texts additionally provide a brief introduction to the bot the kernel's regression tracker uses to facilitate the work, but mention the use is optional. To sum things up, provide a few quotes from Linus in the document for developers to show how serious we take regressions. Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info> Link: https://lore.kernel.org/r/34e56d3588f22d7e0b4d635ef9c9c3b33ca4ac04.1644994117.git.linux@leemhuis.info Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24docs: fix RST error in vm/page_owner.rstJonathan Corbet1-2/+2
Commit f7df2b1cf03a ("tools/vm/page_owner_sort.c: count and sort by mem") added a literal text block without the necessary markup, leading to these warnings in the docs build: Documentation/vm/page_owner.rst:92: WARNING: Unexpected indentation. Documentation/vm/page_owner.rst:96: WARNING: Unexpected indentation. Documentation/vm/page_owner.rst:107: WARNING: Unexpected indentation. Add the necessary colons and make the build quieter. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24Reword note on missing CJK fontsAkira Yokosawa1-3/+10
Use past tense as the fonts can be installed after the fact. Add suggestion to install "Noto Sans CJK" and "Noto Serif CJK" font families. ("Noto Serif CJK" is optional.) Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/dfefa601-c58d-c86c-953f-5e4454db9409@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24docs: kerneldoc-preamble.sty: Expand comments in LaTeX codeAkira Yokosawa1-13/+48
Expand comments in LaTeX code and mention some of important points told in changelogs of conf.py changes. Hopefully they can help future contributors in this area. No code change involved. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/bce9261b-1950-3146-07b2-07bd2ec79158@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24docs: pdfdocs: Pull LaTeX preamble part out of conf.pyAkira Yokosawa2-171/+197
Quote from Jon's remark [1]: I do notice that Documentation/conf.py is getting large and unapproachable. At some future point, it might be nice to pull all of the latex stuff out into a separate file where it won't scare people who stumble into it by accident. Pull LaTeX preamble settings added since commit 3b4c963243b1 ("docs: conf.py: adjust the LaTeX document output") out into sphinx/kerneldoc-preamble.sty. It will be copied to the build directory by the added "latex_additional_files" setting in conf.py. As a bonus, LaTeX/TeX code can be maintained without escaping backslashes. To compensate the loss of change history in sphinx/kerneldoc-preamble.sty, here is a list of changes made in conf.py: - f7ebe6b76940 ("docs: Activate exCJK only in CJK chapters") - 0afd4df0d16a ("docs: pdfdocs: Prevent column squeezing by tabulary") - 659653c9e546 ("docs: pdfdocs: Refactor config for CJK document") - e291ff6f5a03 ("docs: pdfdocs: Add CJK-language-specific font settings") - 7eb368cc319b ("docs: pdfdocs: Choose Serif font as CJK mainfont if possible") - 35382965bdd2 ("docs: pdfdocs: Preserve inter-phrase space in Korean translations") - 77abc2c230b1 ("docs: pdfdocs: One-half spacing for CJK translations") - 788d28a25799 ("docs: pdfdocs: Permit AutoFakeSlant for CJK fonts") - 29ac9822358f ("docs: pdfdocs: Teach xeCJK about character classes of quotation marks") - 7c5c18bdb656 ("docs: pdfdocs: Fix typo in CJK-language specific font settings") - aa872e0647dc ("docs: pdfdocs: Adjust \headheight for fancyhdr") - 8716ef413aa5 ("docs: pdfdocs: Tweak width params of TOC") - 66939df53948 ("docs: pdfdocs: Switch default CJK font to KR variants") - 7b686a2ea1e4 ("docs: pdfdocs: Enable CJKspace in TOC for Korean titles") - 5d9158e3c762 ("docs/translations: Skip CJK contents if suitable fonts not found") - b774cc46313b ("docs: pdfdocs: Move CJK monospace font setting to main conf.py") [1]: https://lore.kernel.org/all/87zgmr66cn.fsf@meer.lwn.net/ Suggested-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/aaa9dca1-27c0-c414-77f3-c5587db0cc5b@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24Documentation: block/diskstats: update function namesNaohiro Aota1-3/+3
__make_request() and end_that_request_last() do no longer exist. Replace them with the current call-site. Signed-off-by: Naohiro Aota <naohiro.aota@wdc.com> Reviewed-by: Chaitanya Kulkarni <kch@nvidia.com> Reviwed-by: Jens Axboe <axboe@kernel.dk> Reviewed-by: Christoph Hellwig <hch@lst.de> Link: https://lore.kernel.org/r/20220222012751.1933194-1-naohiro.aota@wdc.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24Documentation/vm/page_owner.rst: fix languageYixuan Cao1-3/+3
There are some words that need to be fixed. Thanks for Shuah Khan's constructive suggestions. The text has been fixed as follows. a. So, if you'd like to use it, you need to add "page_owner=on" into your boot cmdline. Here, "into" has been replaced with "to". b. ...page owner is disabled in runtime due to no enabling, boot option, runtime overhead is marginal. Here, "no" has been replaced with "not". Signed-off-by: Yixuan Cao <caoyixuan2019@email.szu.edu.cn> Acked-by: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/20220223134104.2663-1-caoyixuan2019@email.szu.edu.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24docs: scripts/kernel-doc: Detect absence of FILE argAkira Yokosawa1-8/+17
Currently, when there is no FILE argument following a switch such as -man, -rst, or -none, kernel-doc exits with a warning from perl (long msg folded): Use of uninitialized value $ARGV[0] in pattern match (m//) at ./scripts/kernel-doc line 438. , which is unhelpful. Improve the behavior by adding a check at the bottom of parsing loop. If the argument is absent, display help text and exit with the code of 1 (via usage()). Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/7b136049-a3ba-0eb5-8717-364d773ff914@gmail.com [jc: reworked to fix conflict with pod patches] Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24scripts: kernel-doc: Refresh the copyright linesTomasz Warniełło1-0/+2
I wanted to clean up these lines, but in the end decided not to touch the old ones and just add my own about POD. I'll leave the cleanup for lawyers. Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Disliked-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220218181628.1411551-12-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24scripts: kernel-doc: Drop obsolete commentsTomasz Warniełło1-143/+0
What for? To improve the script maintainability. 1. License As stated by Jonathan Corbet in the reply to my version 1, the SPDX line is enough. 2. The to-do list comment As suggested by Jonathan Corbet in reply to my version 3, this section doesn't need to be transitioned. And so it is removed for clarity. 3. The historical changelog comments As suggested by Jonathan Corbet in a reply to v3, this section can go. I wanted to keep it, but since it doesn't contain copyright notices, let's just have it clean and simple. 4. The "format of comments" comment block As suggested by Jani Nikula in a reply to my first version of this transformation, Documentation/doc-guide/kernel-doc.rst can serve as the information hub for comment formatting. The section DESCRIPTION already points there, so the original comment block can just be removed. Suggested-by: Jonathan Corbet <corbet@lwn.net> Suggested-by: Jani Nikula <jani.nikula@linux.intel.com> Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Disliked-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220218181628.1411551-11-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24scripts: kernel-doc: Replace the usage functionTomasz Warniełło1-10/+1
Aim: unified POD, user more satisfied, script better structured You can see the results with: $ scripts/kernel-doc -help Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Disliked-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220218181628.1411551-10-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24scripts: kernel-doc: Translate the "Other parameters" subsection of OPTIONSTomasz Warniełło1-5/+18
Aim: unified POD, user more satisfied, script better structured Notes: - The -help token is added. - The entries are sorted alphbetically. Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Disliked-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220218181628.1411551-9-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Copyright © 1996 – 2023 Jason A. Donenfeld. All Rights Reverse Engineered.