summaryrefslogtreecommitdiffstats
path: root/Documentation/process
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2019-05-08 12:42:50 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2019-05-08 12:42:50 -0700
commit8c79f4cd441b27df6cadd11b70a50e06b3b3a2bf (patch)
tree0d7fca2a5fb43fa75b51c4cdaaee493e44d56d62 /Documentation/process
parent2646719a48c21ba0cae82a3f57382a9573fd8400 (diff)
parentd9defe448f4c7b88ca2ae636a321ef8970fa718d (diff)
downloadlinux-8c79f4cd441b27df6cadd11b70a50e06b3b3a2bf.tar.bz2
Merge tag 'docs-5.2' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet: "A reasonably busy cycle for docs, including: - Lots of work on the Chinese and Italian translations - Some license-rules clarifications from Christoph - Various build-script fixes - A new document on memory models - RST conversion of the live-patching docs - The usual collection of typo fixes and corrections" * tag 'docs-5.2' of git://git.lwn.net/linux: (140 commits) docs/livepatch: Unify style of livepatch documentation in the ReST format docs: livepatch: convert docs to ReST and rename to *.rst scripts/documentation-file-ref-check: detect broken :doc:`foo` scripts/documentation-file-ref-check: don't parse Next/ dir LICENSES: Rename other to deprecated LICENSES: Clearly mark dual license only licenses docs: Don't reference the ZLib license in license-rules.rst docs/vm: Minor editorial changes in the THP and hugetlbfs docs/vm: add documentation of memory models doc:it_IT: translation alignment doc: fix typo in PGP guide dontdiff: update with Kconfig build artifacts docs/zh_CN: fix typos in 1.Intro.rst file docs/zh_CN: redirect CoC docs to Chinese version doc: mm: migration doesn't use FOLL_SPLIT anymore docs: doc-guide: remove the extension from .rst files doc: kselftest: Fix KBUILD_OUTPUT usage instructions docs: trace: fix some Sphinx warnings docs: speculation.txt: mark example blocks as such docs: ntb.txt: add blank lines to clean up some Sphinx warnings ...
Diffstat (limited to 'Documentation/process')
-rw-r--r--Documentation/process/5.Posting.rst10
-rw-r--r--Documentation/process/coding-style.rst6
-rw-r--r--Documentation/process/deprecated.rst2
-rw-r--r--Documentation/process/howto.rst2
-rw-r--r--Documentation/process/kernel-docs.rst12
-rw-r--r--Documentation/process/license-rules.rst61
-rw-r--r--Documentation/process/maintainer-pgp-guide.rst2
-rw-r--r--Documentation/process/submitting-patches.rst46
8 files changed, 108 insertions, 33 deletions
diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
index 4213e580f273..855a70b80269 100644
--- a/Documentation/process/5.Posting.rst
+++ b/Documentation/process/5.Posting.rst
@@ -216,10 +216,12 @@ The tags in common use are:
which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
Code without a proper signoff cannot be merged into the mainline.
- - Co-developed-by: states that the patch was also created by another developer
- along with the original author. This is useful at times when multiple
- people work on a single patch. Note, this person also needs to have a
- Signed-off-by: line in the patch as well.
+ - Co-developed-by: states that the patch was co-created by several developers;
+ it is a used to give attribution to co-authors (in addition to the author
+ attributed by the From: tag) when multiple people work on a single patch.
+ Every Co-developed-by: must be immediately followed by a Signed-off-by: of
+ the associated co-author. Details and examples can be found in
+ :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
- Acked-by: indicates an agreement by another developer (often a
maintainer of the relevant code) that the patch is appropriate for
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 8ea913e99fa1..fa864a51e6ea 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -843,7 +843,8 @@ used.
The kernel provides the following general purpose memory allocators:
kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
vzalloc(). Please refer to the API documentation for further information
-about them.
+about them. :ref:`Documentation/core-api/memory-allocation.rst
+<memory_allocation>`
The preferred form for passing a size of a struct is the following:
@@ -874,6 +875,9 @@ The preferred form for allocating a zeroed array is the following:
Both forms check for overflow on the allocation size n * sizeof(...),
and return NULL if that occurred.
+These generic allocation functions all emit a stack dump on failure when used
+without __GFP_NOWARN so there is no use in emitting an additional failure
+message when NULL is returned.
15) The inline disease
----------------------
diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
index 0ef5a63c06ba..49e0f64a3427 100644
--- a/Documentation/process/deprecated.rst
+++ b/Documentation/process/deprecated.rst
@@ -1,5 +1,7 @@
.. SPDX-License-Identifier: GPL-2.0
+.. _deprecated:
+
=====================================================================
Deprecated Interfaces, Language Features, Attributes, and Conventions
=====================================================================
diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
index ad2b6c852b95..6ab75c11d2c3 100644
--- a/Documentation/process/howto.rst
+++ b/Documentation/process/howto.rst
@@ -62,7 +62,7 @@ Legal Issues
The Linux kernel source code is released under the GPL. Please see the file
COPYING in the main directory of the source tree. The Linux kernel licensing
rules and how to use `SPDX <https://spdx.org/>`_ identifiers in source code are
-descibed in :ref:`Documentation/process/license-rules.rst <kernel_licensing>`.
+described in :ref:`Documentation/process/license-rules.rst <kernel_licensing>`.
If you have further questions about the license, please contact a lawyer, and do
not ask on the Linux kernel mailing list. The people on the mailing lists are
not lawyers, and you should not rely on their statements on legal matters.
diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst
index ab12dddc773e..7a45a8e36ea7 100644
--- a/Documentation/process/kernel-docs.rst
+++ b/Documentation/process/kernel-docs.rst
@@ -95,18 +95,6 @@ On-line docs
[...]. This paper examines some common problems for
submitting larger changes and some strategies to avoid problems.
- * Title: **Overview of the Virtual File System**
-
- :Author: Richard Gooch.
- :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt
- :Date: 2007
- :Keywords: VFS, File System, mounting filesystems, opening files,
- dentries, dcache.
- :Description: Brief introduction to the Linux Virtual File System.
- What is it, how it works, operations taken when opening a file or
- mounting a file system and description of important data
- structures explaining the purpose of each of their entries.
-
* Title: **Linux Device Drivers, Third Edition**
:Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman
diff --git a/Documentation/process/license-rules.rst b/Documentation/process/license-rules.rst
index 6b09033a8e9e..2ef44ada3f11 100644
--- a/Documentation/process/license-rules.rst
+++ b/Documentation/process/license-rules.rst
@@ -234,13 +234,13 @@ kernel, can be broken down into:
|
-2. Not recommended licenses:
+2. Deprecated licenses:
These licenses should only be used for existing code or for importing
code from a different project. These licenses are available from the
directory::
- LICENSES/other/
+ LICENSES/deprecated/
in the kernel source tree.
@@ -250,14 +250,14 @@ kernel, can be broken down into:
Examples::
- LICENSES/other/ISC
+ LICENSES/deprecated/ISC
Contains the Internet Systems Consortium license text and the required
metatags::
- LICENSES/other/ZLib
+ LICENSES/deprecated/GPL-1.0
- Contains the ZLIB license text and the required metatags.
+ Contains the GPL version 1 license text and the required metatags.
Metatags:
@@ -281,7 +281,56 @@ kernel, can be broken down into:
|
-3. _`Exceptions`:
+3. Dual Licensing Only
+
+ These licenses should only be used to dual license code with another
+ license in addition to a preferred license. These licenses are available
+ from the directory::
+
+ LICENSES/dual/
+
+ in the kernel source tree.
+
+ The files in this directory contain the full license text and
+ `Metatags`_. The file names are identical to the SPDX license
+ identifier which shall be used for the license in source files.
+
+ Examples::
+
+ LICENSES/dual/MPL-1.1
+
+ Contains the Mozilla Public License version 1.1 license text and the
+ required metatags::
+
+ LICENSES/dual/Apache-2.0
+
+ Contains the Apache License version 2.0 license text and the required
+ metatags.
+
+ Metatags:
+
+ The metatag requirements for 'other' licenses are identical to the
+ requirements of the `Preferred licenses`_.
+
+ File format example::
+
+ Valid-License-Identifier: MPL-1.1
+ SPDX-URL: https://spdx.org/licenses/MPL-1.1.html
+ Usage-Guide:
+ Do NOT use. The MPL-1.1 is not GPL2 compatible. It may only be used for
+ dual-licensed files where the other license is GPL2 compatible.
+ If you end up using this it MUST be used together with a GPL2 compatible
+ license using "OR".
+ To use the Mozilla Public License version 1.1 put the following SPDX
+ tag/value pair into a comment according to the placement guidelines in
+ the licensing rules documentation:
+ SPDX-License-Identifier: MPL-1.1
+ License-Text:
+ Full license text
+
+|
+
+4. _`Exceptions`:
Some licenses can be amended with exceptions which grant certain rights
which the original license does not. These exceptions are available
diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst
index aff9b1a4d77b..4bab7464ff8c 100644
--- a/Documentation/process/maintainer-pgp-guide.rst
+++ b/Documentation/process/maintainer-pgp-guide.rst
@@ -943,7 +943,7 @@ have on your keyring::
Next, open the `PGP pathfinder`_. In the "From" field, paste the key
fingerprint of Linus Torvalds from the output above. In the "To" field,
-paste they key-id you found via ``gpg --search`` of the unknown key, and
+paste the key-id you found via ``gpg --search`` of the unknown key, and
check the results:
- `Finding paths to Linus`_
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index be7d1829c3af..9c4299293c72 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -60,8 +60,8 @@ not in any lower subdirectory.
To create a patch for a single file, it is often sufficient to do::
- SRCTREE= linux
- MYFILE= drivers/net/mydriver.c
+ SRCTREE=linux
+ MYFILE=drivers/net/mydriver.c
cd $SRCTREE
cp $MYFILE $MYFILE.orig
@@ -73,7 +73,7 @@ To create a patch for multiple files, you should unpack a "vanilla",
or unmodified kernel source tree, and generate a ``diff`` against your
own source tree. For example::
- MYSRC= /devel/linux
+ MYSRC=/devel/linux
tar xvfz linux-3.19.tar.gz
mv linux-3.19 linux-3.19-vanilla
@@ -545,10 +545,40 @@ person it names - but it should indicate that this person was copied on the
patch. This tag documents that potentially interested parties
have been included in the discussion.
-A Co-developed-by: states that the patch was also created by another developer
-along with the original author. This is useful at times when multiple people
-work on a single patch. Note, this person also needs to have a Signed-off-by:
-line in the patch as well.
+Co-developed-by: states that the patch was co-created by multiple developers;
+it is a used to give attribution to co-authors (in addition to the author
+attributed by the From: tag) when several people work on a single patch. Since
+Co-developed-by: denotes authorship, every Co-developed-by: must be immediately
+followed by a Signed-off-by: of the associated co-author. Standard sign-off
+procedure applies, i.e. the ordering of Signed-off-by: tags should reflect the
+chronological history of the patch insofar as possible, regardless of whether
+the author is attributed via From: or Co-developed-by:. Notably, the last
+Signed-off-by: must always be that of the developer submitting the patch.
+
+Note, the From: tag is optional when the From: author is also the person (and
+email) listed in the From: line of the email header.
+
+Example of a patch submitted by the From: author::
+
+ <changelog>
+
+ Co-developed-by: First Co-Author <first@coauthor.example.org>
+ Signed-off-by: First Co-Author <first@coauthor.example.org>
+ Co-developed-by: Second Co-Author <second@coauthor.example.org>
+ Signed-off-by: Second Co-Author <second@coauthor.example.org>
+ Signed-off-by: From Author <from@author.example.org>
+
+Example of a patch submitted by a Co-developed-by: author::
+
+ From: From Author <from@author.example.org>
+
+ <changelog>
+
+ Co-developed-by: Random Co-Author <random@coauthor.example.org>
+ Signed-off-by: Random Co-Author <random@coauthor.example.org>
+ Signed-off-by: From Author <from@author.example.org>
+ Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
+ Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
@@ -696,7 +726,7 @@ A couple of example Subjects::
The ``from`` line must be the very first line in the message body,
and has the form:
- From: Original Author <author@example.com>
+ From: Patch Author <author@example.com>
The ``from`` line specifies who will be credited as the author of the
patch in the permanent changelog. If the ``from`` line is missing,