summaryrefslogtreecommitdiff
path: root/Documentation/process
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2023-08-31 06:05:42 +0300
committerLinus Torvalds <torvalds@linux-foundation.org>2023-08-31 06:05:42 +0300
commitcd99b9eb4b702563c5ac7d26b632a628f5a832a5 (patch)
treeff96773806b6bb1efece11d8b7678ae43d71411e /Documentation/process
parentf8fd5c24830fbc259ba7d5e72817c9867c01b8e8 (diff)
parentc63594f2d66690805eb78b75e4b8e8dc9f2672bf (diff)
downloadlinux-cd99b9eb4b702563c5ac7d26b632a628f5a832a5.tar.xz
Merge tag 'docs-6.6' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet: "Documentation work keeps chugging along; this includes: - Work from Carlos Bilbao to integrate rustdoc output into the generated HTML documentation. This took some work to figure out how to do it without slowing the docs build and without creating people who don't have Rust installed, but Carlos got there - Move the loongarch and mips architecture documentation under Documentation/arch/ - Some more maintainer documentation from Jakub ... plus the usual assortment of updates, translations, and fixes" * tag 'docs-6.6' of git://git.lwn.net/linux: (56 commits) Docu: genericirq.rst: fix irq-example input: docs: pxrc: remove reference to phoenix-sim Documentation: serial-console: Fix literal block marker docs/mm: remove references to hmm_mirror ops and clean typos docs/zh_CN: correct regi_chg(),regi_add() to region_chg(),region_add() Documentation: Fix typos Documentation/ABI: Fix typos scripts: kernel-doc: fix macro handling in enums scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN] Documentation: riscv: Update boot image header since EFI stub is supported Documentation: riscv: Add early boot document Documentation: arm: Add bootargs to the table of added DT parameters docs: kernel-parameters: Refer to the correct bitmap function doc: update params of memhp_default_state= docs: Add book to process/kernel-docs.rst docs: sparse: fix invalid link addresses docs: vfs: clean up after the iterate() removal docs: Add a section on surveys to the researcher guidelines docs: move mips under arch docs: move loongarch under arch ...
Diffstat (limited to 'Documentation/process')
-rw-r--r--Documentation/process/botching-up-ioctls.rst2
-rw-r--r--Documentation/process/changes.rst16
-rw-r--r--Documentation/process/deprecated.rst2
-rw-r--r--Documentation/process/kernel-docs.rst11
-rw-r--r--Documentation/process/researcher-guidelines.rst27
5 files changed, 45 insertions, 13 deletions
diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst
index 9739b88463a5..a05e8401de1c 100644
--- a/Documentation/process/botching-up-ioctls.rst
+++ b/Documentation/process/botching-up-ioctls.rst
@@ -208,7 +208,7 @@ Not every problem needs a new ioctl:
it's much quicker to push a driver-private interface than engaging in
lengthy discussions for a more generic solution. And occasionally doing a
private interface to spearhead a new concept is what's required. But in the
- end, once the generic interface comes around you'll end up maintainer two
+ end, once the generic interface comes around you'll end up maintaining two
interfaces. Indefinitely.
* Consider other interfaces than ioctls. A sysfs attribute is much better for
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index 0bbd040f6a55..b48da698d6f2 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -482,7 +482,7 @@ E2fsprogs
JFSutils
--------
-- <http://jfs.sourceforge.net/>
+- <https://jfs.sourceforge.net/>
Reiserfsprogs
-------------
@@ -503,7 +503,7 @@ Pcmciautils
Quota-tools
-----------
-- <http://sourceforge.net/projects/linuxquota/>
+- <https://sourceforge.net/projects/linuxquota/>
Intel P6 microcode
@@ -524,7 +524,7 @@ FUSE
mcelog
------
-- <http://www.mcelog.org/>
+- <https://www.mcelog.org/>
cpio
----
@@ -544,7 +544,8 @@ PPP
NFS-utils
---------
-- <http://sourceforge.net/project/showfiles.php?group_id=14>
+- <https://sourceforge.net/project/showfiles.php?group_id=14>
+- <https://nfs.sourceforge.net/>
Iptables
--------
@@ -559,12 +560,7 @@ Ip-route2
OProfile
--------
-- <http://oprofile.sf.net/download/>
-
-NFS-Utils
----------
-
-- <http://nfs.sourceforge.net/>
+- <https://oprofile.sf.net/download/>
Kernel documentation
********************
diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
index f91b8441f2ef..1f7f3e6c9cda 100644
--- a/Documentation/process/deprecated.rst
+++ b/Documentation/process/deprecated.rst
@@ -77,7 +77,7 @@ kzalloc() can be replaced with kcalloc().
If no 2-factor form is available, the saturate-on-overflow helpers should
be used::
- bar = vmalloc(array_size(count, size));
+ bar = dma_alloc_coherent(dev, array_size(count, size), &dma, GFP_KERNEL);
Another common case to avoid is calculating the size of a structure with
a trailing array of others structures, as in::
diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst
index 46f927aae6eb..8660493b91d0 100644
--- a/Documentation/process/kernel-docs.rst
+++ b/Documentation/process/kernel-docs.rst
@@ -29,7 +29,7 @@ All documents are cataloged with the following fields: the document's
The documents on each section of this document are ordered by its
published date, from the newest to the oldest. The maintainer(s) should
- periodically retire resources as they become obsolte or outdated; with
+ periodically retire resources as they become obsolete or outdated; with
the exception of foundational books.
Docs at the Linux Kernel tree
@@ -118,6 +118,15 @@ 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**
diff --git a/Documentation/process/researcher-guidelines.rst b/Documentation/process/researcher-guidelines.rst
index 9fcfed3c350b..d159cd4f5e5b 100644
--- a/Documentation/process/researcher-guidelines.rst
+++ b/Documentation/process/researcher-guidelines.rst
@@ -44,6 +44,33 @@ explicit agreement of, and full disclosure to, the individual developers
involved. Developers cannot be interacted with/experimented on without
consent; this, too, is standard research ethics.
+Surveys
+=======
+
+Research often takes the form of surveys sent to maintainers or
+contributors. As a general rule, though, the kernel community derives
+little value from these surveys. The kernel development process works
+because every developer benefits from their participation, even working
+with others who have different goals. Responding to a survey, though, is a
+one-way demand placed on busy developers with no corresponding benefit to
+themselves or to the kernel community as a whole. For this reason, this
+method of research is discouraged.
+
+Kernel community members already receive far too much email and are likely
+to perceive survey requests as just another demand on their time. Sending
+such requests deprives the community of valuable contributor time and is
+unlikely to yield a statistically useful response.
+
+As an alternative, researchers should consider attending developer events,
+hosting sessions where the research project and its benefits to the
+participants can be explained, and interacting directly with the community
+there. The information received will be far richer than that obtained from
+an email survey, and the community will gain from the ability to learn from
+your insights as well.
+
+Patches
+=======
+
To help clarify: sending patches to developers *is* interacting
with them, but they have already consented to receiving *good faith
contributions*. Sending intentionally flawed/vulnerable patches or