Re: [patch V5 01/11] Documentation: Add license-rules.rst to describe how to properly identify file licenses

[Philippe Ombredanne]

Thomas,

On Thu, Dec 28, 2017 at 11:17 PM, Thomas Gleixner <tglx@xxxxxxxxxxxxx> wrote:
> On Thu, 28 Dec 2017, Thomas Gleixner wrote:
>
> Sorry for the spam. I somehow missed to refresh the patch before generating
> the mbox. Find below the correct version of that one which has ALL braces
> removed which we don't need.
>
> Thanks,
>
>         tglx
>
> 8<--------------------------
> Subject: Documentation: Add license-rules.rst to describe how to properly identify file licenses
> From: Thomas Gleixner <tglx@xxxxxxxxxxxxx>
> Date: Fri, 10 Nov 2017 09:30:00 +0100
>
> Add a file to the Documentation directory to describe how file licenses
> should be described in all kernel files, using the SPDX identifier, as well
> as where all licenses should be in the kernel source tree for people to
> refer to (LICENSES/).
>
> Thanks to Kate and Greg for review and editing and Jonas for the
> suggestions concerning the meta tags in the licenses files.
>
> Signed-off-by: Thomas Gleixner <tglx@xxxxxxxxxxxxx>
> Reviewed-by: Jonas Oberg <jonas@xxxxxxxx>
> Reviewed-by: Jonathan Corbet <corbet@xxxxxxx>
> Reviewed-by: Philippe Ombredanne <pombredanne@xxxxxxxx>
> Reviewed-by: Kate Stewart <kstewart@xxxxxxxxxxxxxxxxxxx>
> Reviewed-by: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
>
> ---
>  Documentation/index.rst                 |   12 +
>  Documentation/process/license-rules.rst |  370 ++++++++++++++++++++++++++++++++
>  2 files changed, 382 insertions(+)
>  create mode 100644 Documentation/license-rules.rst
>
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -13,6 +13,18 @@ documents into a coherent whole.  Please
>  documentation are welcome; join the linux-doc list at vger.kernel.org if
>  you want to help out.
>
> +Licensing documentation
> +-----------------------
> +
> +The following describes the license of the Linux kernel source code
> +(GPLv2), how to properly mark the license of individual files in the source
> +tree, as well as links to the full license text.
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   process/license-rules.rst
> +
>  User-oriented documentation
>  ---------------------------
>
> --- /dev/null
> +++ b/Documentation/process/license-rules.rst
> @@ -0,0 +1,370 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Linux kernel licensing rules
> +============================
> +
> +The Linux Kernel is provided under the terms of the GNU General Public
> +License version 2 only (GPL-2.0), as published by the Free Software
> +Foundation, and provided in the COPYING file.  This documentation file is
> +not meant to replace the COPYING file, but provides a description of how
> +each source file should be annotated to make the licensing it is governed
> +under clear and unambiguous.
> +
> +The license in the COPYING file applies to the kernel source as a whole,
> +though individual source files can have a different license which is
> +required to be compatible with the GPL-2.0::
> +
> +    GPL-1.0+  :  GNU General Public License v1.0 or later
> +    GPL-2.0+  :  GNU General Public License v2.0 or later
> +    LGPL-2.0  :  GNU Library General Public License v2 only
> +    LGPL-2.0+ :  GNU Library General Public License v2 or later
> +    LGPL-2.1  :  GNU Lesser General Public License v2.1 only
> +    LGPL-2.1+ :  GNU Lesser General Public License v2.1 or later
> +
> +Aside from that, individual files can be provided under a dual license,
> +e.g. one of the compatible GPL variants and alternatively under a
> +permissive license like BSD, MIT etc.
> +
> +The User-space API (UAPI) header files, which describe the interface of
> +user-space programs to the kernel are a special case.  According to the
> +note in the kernel COPYING file, the syscall interface is a clear boundary,
> +which does not extend the GPL requirements to any software which uses it to
> +communicate with the kernel.  Because the UAPI headers must be includable
> +into any source files which create an executable running on the Linux
> +kernel, the exception must be documented by a special license expression.
> +
> +The common way of expressing the license of a source file is to add the
> +matching boilerplate text into the top comment of the file.  Due to
> +formatting, typos etc. these "boilerplates" are hard to validate for
> +tools which are used in the context of license compliance.
> +
> +An alternative to boilerplate text is the use of Software Package Data
> +Exchange (SPDX) license identifiers in each source file.  SPDX license
> +identifiers are machine parsable and precise shorthands for the license
> +under which the content of the file is contributed.  SPDX license
> +identifiers are managed by the SPDX Workgroup at the Linux Foundation and
> +have been agreed on by partners throughout the industry, tool vendors, and
> +legal teams.  For further information see https://spdx.org/
> +
> +The Linux kernel requires the precise SPDX identifier in all source files.
> +The valid identifiers used in the kernel are explained in the section
> +`License identifiers`_ and have been retrieved from the official SPDX
> +license list at https://spdx.org/licenses/ along with the license texts.
> +
> +License identifier syntax
> +-------------------------
> +
> +1. Placement:
> +
> +   The SPDX license identifier in kernel files shall be added at the first
> +   possible line in a file which can contain a comment.  For the majority
> +   or files this is the first line, except for scripts which require the
> +   '#!PATH_TO_INTERPRETER' in the first line.  For those scripts the SPDX
> +   identifier goes into the second line.
> +
> +|
> +
> +2. Style:
> +
> +   The SPDX license identifier is added in form of a comment.  The comment
> +   style depends on the file type::
> +
> +      C source:        // SPDX-License-Identifier: <SPDX License Expression>
> +      C header:        /* SPDX-License-Identifier: <SPDX License Expression> */
> +      ASM:     /* SPDX-License-Identifier: <SPDX License Expression> */
> +      scripts: # SPDX-License-Identifier: <SPDX License Expression>
> +      .rst:    .. SPDX-License-Identifier: <SPDX License Expression>
> +      .dts{i}: // SPDX-License-Identifier: <SPDX License Expression>
> +
> +   If a specific tool cannot handle the standard comment style, then the
> +   appropriate comment mechanism which the tool accepts shall be used. This
> +   is the reason for having the "/\* \*/" style comment in C header
> +   files. There was build breakage observed with generated .lds files where
> +   'ld' failed to parse the C++ comment. This has been fixed by now, but
> +   there are still older assembler tools which cannot handle C++ style
> +   comments.
> +
> +|
> +
> +3. Syntax:
> +
> +   A <SPDX License Expression> is either an SPDX short form license
> +   identifier found on the SPDX License List, or the combination of two
> +   SPDX short form license identifiers separated by "WITH" when a license
> +   exception applies. When multiple licenses apply, an expression consists
> +   of keywords "AND", "OR" separating sub-expressions and surrounded by
> +   "(", ")" .
> +
> +   License identifiers for licenses like [L]GPL with the 'or later' option
> +   are constructed by using a "+" for indicating the 'or later' option.::
> +
> +      // SPDX-License-Identifier: GPL-2.0+
> +      // SPDX-License-Identifier: LGPL-2.1+
> +
> +   WITH should be used when there is a modifier to a license needed.
> +   For example, the linux kernel UAPI files use the expression::
> +
> +      // SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note
> +      // SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note
> +
> +   Other examples using WITH exceptions found in the kernel are::
> +
> +      // SPDX-License-Identifier: GPL-2.0 WITH mif-exception
> +      // SPDX-License-Identifier: GPL-2.0+ WITH GCC-exception-2.0
> +
> +   Exceptions can only be used with particular License identifiers. The
> +   valid License identifiers are listed in the tags of the exception text
> +   file. For details see the point `Exceptions`_ in the chapter `License
> +   identifiers`_.
> +
> +   OR should be used if the file is dual licensed and only one license is
> +   to be selected.  For example, some dtsi files are available under dual
> +   licenses::
> +
> +      // SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause
> +
> +   Examples from the kernel for license expressions in dual licensed files::
> +
> +      // SPDX-License-Identifier: GPL-2.0 OR MIT
> +      // SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
> +      // SPDX-License-Identifier: GPL-2.0 OR Apache-2.0
> +      // SPDX-License-Identifier: GPL-2.0 OR MPL-1.1
> +      // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) OR MIT
> +      // SPDX-License-Identifier: GPL-1.0+ OR BSD-3-Clause OR OpenSSL
> +
> +   AND should be used if the file has multiple licenses whose terms all
> +   apply to use the file. For example, if code is inherited from another
> +   project and permission has been given to put it in the kernel, but the
> +   original license terms need to remain in effect::
> +
> +      // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) AND MIT
> +
> +   Another other example where both sets of license terms need to be
> +   adhered to is::
> +
> +      // SPDX-License-Identifier: GPL-1.0+ AND LGPL-2.1+
> +
> +License identifiers
> +-------------------
> +
> +The licenses currently used, as well as the licenses for code added to the
> +kernel, can be broken down into:
> +
> +1. _`Preferred licenses`:
> +
> +   Whenever possible these licenses should be used as they are known to be
> +   fully compatible and widely used.  These licenses are available from the
> +   directory::
> +
> +      LICENSES/preferred/
> +
> +   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/preferred/GPL-2.0
> +
> +   Contains the GPL version 2 license text and the required metatags::
> +
> +      LICENSES/preferred/MIT
> +
> +   Contains the MIT license text and the required metatags
> +
> +   _`Metatags`:
> +
> +   The following meta tags must be available in a license file:
> +
> +   - Valid-License-Identifier:
> +
> +     One or more lines which declare which License Identifiers are valid
> +     inside the project to reference this particular license text.  Usually
> +     this is a single valid identifier, but e.g. for licenses with the 'or
> +     later' options two identifiers are valid.
> +
> +   - SPDX-URL:
> +
> +     The URL of the SPDX page which contains additional information related
> +     to the license.
> +
> +   - Usage-Guidance:
> +
> +     Freeform text for usage advice. The text must include correct examples
> +     for the SPDX license identifiers as they should be put into source
> +     files according to the `License identifier syntax`_ guidelines.
> +
> +   - License-Text:
> +
> +     All text after this tag is treated as the original license text
> +
> +   File format examples::
> +
> +      Valid-License-Identifier: GPL-2.0
> +      Valid-License-Identifier: GPL-2.0+
> +      SPDX-URL: https://spdx.org/licenses/GPL-2.0.html
> +      Usage-Guide:
> +        To use this license in source code, put one of the following SPDX
> +       tag/value pairs into a comment according to the placement
> +       guidelines in the licensing rules documentation.
> +       For 'GNU General Public License (GPL) version 2 only' use:
> +         SPDX-License-Identifier: GPL-2.0
> +       For 'GNU General Public License (GPL) version 2 or any later version' use:
> +         SPDX-License-Identifier: GPL-2.0+
> +      License-Text:
> +        Full license text
> +
> +   ::
> +
> +      SPDX-License-Identifier: MIT
> +      SPDX-URL: https://spdx.org/licenses/MIT.html
> +      Usage-Guide:
> +       To use this license in source code, put the following SPDX
> +       tag/value pair into a comment according to the placement
> +       guidelines in the licensing rules documentation.
> +         SPDX-License-Identifier: MIT
> +      License-Text:
> +        Full license text
> +
> +|
> +
> +2. Not recommended 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/
> +
> +   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/other/ISC
> +
> +   Contains the Internet Systems Consortium license text and the required
> +   metatags::
> +
> +      LICENSES/other/ZLib
> +
> +   Contains the ZLIB 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: ISC
> +      SPDX-URL: https://spdx.org/licenses/ISC.html
> +      Usage-Guide:
> +        Usage of this license in the kernel for new code is discouraged
> +       and it should solely be used for importing code from an already
> +       existing project.
> +        To use this license in source code, put the following SPDX
> +       tag/value pair into a comment according to the placement
> +       guidelines in the licensing rules documentation.
> +         SPDX-License-Identifier: ISC
> +      License-Text:
> +        Full license text
> +
> +|
> +
> +3. _`Exceptions`:
> +
> +   Some licenses can be amended with exceptions which grant certain rights
> +   which the original license does not.  These exceptions are available
> +   from the directory::
> +
> +      LICENSES/exceptions/
> +
> +   in the kernel source tree.  The files in this directory contain the full
> +   exception text and the required `Exception Metatags`_.
> +
> +   Examples::
> +
> +      LICENSES/exceptions/Linux-syscall-note
> +
> +   Contains the Linux syscall exception as documented in the COPYING
> +   file of the Linux kernel, which is used for UAPI header files.
> +   e.g. /\* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note \*/::
> +
> +      LICENSES/exceptions/GCC-exception-2.0
> +
> +   Contains the GCC 'linking exception' which allows to link any binary
> +   independent of its license against the compiled version of a file marked
> +   with this exception. This is required for creating runnable executables
> +   from source code which is not compatible with the GPL.
> +
> +   _`Exception Metatags`:
> +
> +   The following meta tags must be available in an exception file:
> +
> +   - SPDX-Exception-Identifier:
> +
> +     One exception identifier which can be used with SPDX license
> +     identifiers.
> +
> +   - SPDX-URL:
> +
> +     The URL of the SPDX page which contains additional information related
> +     to the exception.
> +
> +   - SPDX-Licenses:
> +
> +     A comma separated list of SPDX license identifiers for which the
> +     exception can be used.
> +
> +   - Usage-Guidance:
> +
> +     Freeform text for usage advice. The text must be followed by correct
> +     examples for the SPDX license identifiers as they should be put into
> +     source files according to the `License identifier syntax`_ guidelines.
> +
> +   - Exception-Text:
> +
> +     All text after this tag is treated as the original exception text
> +
> +   File format examples::
> +
> +      SPDX-Exception-Identifier: Linux-syscall-note
> +      SPDX-URL: https://spdx.org/licenses/Linux-syscall-note.html
> +      SPDX-Licenses: GPL-2.0, GPL-2.0+, GPL-1.0+, LGPL-2.0, LGPL-2.0+, LGPL-2.1, LGPL-2.1+
> +      Usage-Guidance:
> +        This exception is used together with one of the above SPDX-Licenses
> +       to mark user-space API (uapi) header files so they can be included
> +       into non GPL compliant user-space application code.
> +        To use this exception add it with the keyword WITH to one of the
> +       identifiers in the SPDX-Licenses tag:
> +         SPDX-License-Identifier: <SPDX-License> WITH Linux-syscall-note
> +      Exception-Text:
> +        Full exception text
> +
> +   ::
> +
> +      SPDX-Exception-Identifier: GCC-exception-2.0
> +      SPDX-URL: https://spdx.org/licenses/GCC-exception-2.0.html
> +      SPDX-Licenses: GPL-2.0, GPL-2.0+
> +      Usage-Guidance:
> +        The "GCC Runtime Library exception 2.0" is used together with one
> +       of the above SPDX-Licenses for code imported from the GCC runtime
> +       library.
> +        To use this exception add it with the keyword WITH to one of the
> +       identifiers in the SPDX-Licenses tag:
> +         SPDX-License-Identifier: <SPDX-License> WITH GCC-exception-2.0
> +      Exception-Text:
> +        Full exception text
> +
> +
> +All SPDX license identifiers and exceptions must have a corresponding file
> +in the LICENSE subdirectories. This is required to allow tool
> +verification (e.g. checkpatch.pl) and to have the licenses ready to read
> +and extract right from the source, which is recommended by various FOSS
> +organizations, e.g. the `FSFE REUSE initiative <https://reuse.software/>`_.

My review still stands in this updated/corrected version. Thanks!

Reviewed-by: Philippe Ombredanne <pombredanne@xxxxxxxx>

-- 
Cordially
Philippe Ombredanne