diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2019-05-08 12:42:50 -0700 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2019-05-08 12:42:50 -0700 |
commit | 8c79f4cd441b27df6cadd11b70a50e06b3b3a2bf (patch) | |
tree | 0d7fca2a5fb43fa75b51c4cdaaee493e44d56d62 /Documentation/process | |
parent | 2646719a48c21ba0cae82a3f57382a9573fd8400 (diff) | |
parent | d9defe448f4c7b88ca2ae636a321ef8970fa718d (diff) | |
download | linux-8c79f4cd441b27df6cadd11b70a50e06b3b3a2bf.tar.gz linux-8c79f4cd441b27df6cadd11b70a50e06b3b3a2bf.tar.bz2 linux-8c79f4cd441b27df6cadd11b70a50e06b3b3a2bf.zip |
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.rst | 10 | ||||
-rw-r--r-- | Documentation/process/coding-style.rst | 6 | ||||
-rw-r--r-- | Documentation/process/deprecated.rst | 2 | ||||
-rw-r--r-- | Documentation/process/howto.rst | 2 | ||||
-rw-r--r-- | Documentation/process/kernel-docs.rst | 12 | ||||
-rw-r--r-- | Documentation/process/license-rules.rst | 61 | ||||
-rw-r--r-- | Documentation/process/maintainer-pgp-guide.rst | 2 | ||||
-rw-r--r-- | Documentation/process/submitting-patches.rst | 46 |
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, |