From d27e6304d0968e0826243a44dda7a09e0cb75dd4 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 19 Feb 2020 08:05:57 +0100 Subject: eng: Rework file template section Update #3053. --- eng/coding-file-hdr.rst | 270 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 240 insertions(+), 30 deletions(-) diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst index c724c5d..6261b49 100644 --- a/eng/coding-file-hdr.rst +++ b/eng/coding-file-hdr.rst @@ -1,45 +1,255 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018. -.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project +.. Copyright (C) 2018, 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2018, 2020 Sebastian Huber -.. COMMENT:TBD - Convert the following to Rest and insert into this file -.. COMMENT:TBD - https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header +File Templates +============== +Every source code file shall have a copyright and license block. Corresponding +to the licence, every file shall have an +`SPDX License Identifier `_ in the first possible line +of the file. C/C++ files should have a Doxygen file comment block. -Boilerplate File Header -======================= +The preferred license for source code is +`BSD-2-Clause `_. The preferred +license for documentation is +`CC-BY-SA-4.0 `_. -Every file should include two comment header blocks, one for the Doxygen -output and a copyright notice. This is a typical example: +.. _FileHeaderCopyright: + +Copyright and License Block +--------------------------- + +You are the copyright holder. Use the following copyright and license block for +your source code contributions to the RTEMS Project. Place it after the SPDX +License Identifier line and the optional file documentation block. Replace the + placeholder with the year of your first substantial contribution to +this file. Update the with the year of your last substantial +contribution to this file. If the first and last years are the same, then +remove the placeholder with the comma. Replace the placeholder with your name. + +In case you are a real person, then use the following format for +: . The +is your first name (also known as given name), the are your +optional middle names, the is your last name (also known as family +name). + +If more than one copyright holder exists for a file, then sort the copyright +lines by the first year (earlier years are below later years) followed by the +copyright holder in alphabetical order (A is above B in the file). + +Use the following template for a copyright and license block. Do not change the +license text. + +.. code-block:: none + + Copyright (C) , + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + +Check the top-level :file:`COPYING` file of the repository. If you are a new +copyright holder, then add yourself to the top of the list. If your last year +of a substantial contribution changed, then please update your copyright line. + +C/C++ Header File Template +-------------------------- + +Use the following guidelines and template for C and C++ header files (here +:file:``): + +* Place the SPDX License Identifier in the first line of the file. + +* Add a Doxygen file documentation block. + +* Place the copyright and license comment block after the documentation block. + +* For the , , and placeholders see + :ref:`FileHeaderCopyright`. + +* Separate comment blocks by exactly one blank line. + +* Separate the Doxygen comment block from the copyright and license, so that + the copyright and license information is not included in the Doxygen output. + +* For C++ header files discard the extern "C". + +.. code-block:: c + + /* SPDX-License-Identifier: BSD-2-Clause + + /** + * @file + * + * @ingroup TheGroupForThisFile + * + * @brief Short "Table of Contents" Description of File Contents + * + * A short description of the purpose of this file. + */ + + /* + * Copyright (C) , + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + + #ifndef _FOO_BAR_BAZ_H + #define _FOO_BAR_BAZ_H + + #include + + #ifdef __cplusplus + extern "C" { + #endif + + /* Declarations, defines, macros, inline functions, etc. */ + + #ifdef __cplusplus + } + #endif + + #endif /* _FOO_BAR_BAZ_H */ + +C/C++/Assembler Source File Template +------------------------------------ + +Use the following template for C, C++, and assembler source files (here +implementation of :file:``). For the , , +and placeholders see :ref:`FileHeaderCopyright`. .. code-block:: c - /** - * @file - * - * @ingroup TheGroupForThisFile - * - * @brief Short "Table of Contents" Description of File Contents - * - * A short description of the purpose of this file. - */ + /* SPDX-License-Identifier: BSD-2-Clause */ + + /** + * @file + * + * @ingroup TheGroupForThisFile + * + * @brief Short "Table of Contents" Description of File Contents + * + * A short description of the purpose of this file. + */ + + /* + * Copyright (C) , + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + + #if HAVE_CONFIG_H + #include "config.h" + #endif + + #include + + /* Definitions, etc. */ + +Python File Template +-------------------- + +Use the following template for Python source files and other files which accept +a ``#``-style comment block. For the , , and + placeholders see :ref:`FileHeaderCopyright`. + +.. code-block:: python + + #!/usr/bin/env python + # SPDX-License-Identifier: BSD-2-Clause + + # File documentation block - /* - * Copyright (c) 20XX Your Name Or Your Company. - * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * https://www.rtems.org/license/LICENSE. - */ + # Copyright (C) , + # + # Redistribution and use in source and binary forms, with or without + # modification, are permitted provided that the following conditions + # are met: + # 1. Redistributions of source code must retain the above copyright + # notice, this list of conditions and the following disclaimer. + # 2. Redistributions in binary form must reproduce the above copyright + # notice, this list of conditions and the following disclaimer in the + # documentation and/or other materials provided with the distribution. + # + # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + # ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + # CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + # POSSIBILITY OF SUCH DAMAGE. +reStructuredText File Template +------------------------------ -* Use exactly one blank line between the Doxygen header and copyright notice. - Leave the first line of the copyright notice blank. +Use the following template for reStructuredText (reST) source files. For the +, , and placeholders see +:ref:`FileHeaderCopyright`. -* Separate the Doxygen header and copyright notice so the copyright notice is - not included in the Doxygen output. +.. code-block:: rest -* The copyright owner and specific license terms may vary. + .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. COMMENT: TBD - TBD Add link to license requirements section and show variant licenses. + .. Copyright (C) , -- cgit v1.2.3