Update #3053. --- v2: Clarify COPYING update and placeholders.
v3: * Prefer verbatim licence texts. * Add Python file template. eng/coding-file-hdr.rst | 251 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 221 insertions(+), 30 deletions(-) diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst index c724c5d..b7f08b0 100644 --- a/eng/coding-file-hdr.rst +++ b/eng/coding-file-hdr.rst @@ -1,45 +1,236 @@ .. 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 +.. (https://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 file shall have a copyright and license comment block. C/C++ files should +have a Doxygen file comment block. -Boilerplate File Header -======================= +The preferred licence for new source code is +`BSD-2-Clause <https://spdx.org/licenses/BSD-2-Clause.html>`_. -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 Comment Block +----------------------------------- + +You are the copyright holder. Copy the comment below the top of the file in +which you want to use this license for your contribution. Replace the +<FIRST YEAR> placeholder with the year of your first substantial contribution to +this file. Update the <LAST YEAR> with the year of your last substantial +contribution to this file. If the first and last years are the same, then +remove the <LAST YEAR> placeholder with the comma. Replace the +<COPYRIGHT HOLDER> placeholder with your name. + +In case you are a real person, then use the following format for +<COPYRIGHT HOLDER>: <FIRST NAME> <MIDDLE NAMES> <LAST NAME>. The <FIRST NAME> +is your first name (also known as given name), the <MIDDLE NAMES> are your +optional middle names, the <LAST NAME> 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 comment block. Do not +change the licence text. + +.. code-block:: none + + SPDX-License-Identifier: BSD-2-Clause + + Copyright (C) <FIRST YEAR>, <LAST YEAR> <COPYRIGHT HOLDER> + + 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:`<foo/bar/baz.h>`): + +* Place the copyright and license comment block to the top of the file. + +* For the <FIRST YEAR>, <LAST YEAR>, and <COPYRIGHT HOLDER> placeholders see + :ref:`FileHeaderCopyright`. + +* Use exactly one blank line between the copyright and licence comment block and + the Doxygen comment block. + +* 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 - /** - * @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 + * + * Copyright (C) <FIRST YEAR>, <LAST YEAR> <COPYRIGHT HOLDER> + * + * 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. + */ + + /** + * @file + * + * @ingroup TheGroupForThisFile + * + * @brief Short "Table of Contents" Description of File Contents + * + * A short description of the purpose of this file. + */ + + #ifndef _FOO_BAR_BAZ_H + #define _FOO_BAR_BAZ_H + + #include <foo/bar/xyz.h> + + #ifdef __cplusplus + extern "C" { + #endif - /* - * 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. - */ + /* Declarations, defines, macros, inline functions, etc. */ + #ifdef __cplusplus + } + #endif -* Use exactly one blank line between the Doxygen header and copyright notice. - Leave the first line of the copyright notice blank. + #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:`<foo/bar/baz.h>`). For the <FIRST YEAR>, <LAST YEAR>, +and <COPYRIGHT HOLDER> placeholders see :ref:`FileHeaderCopyright`. + +.. code-block:: c -* Separate the Doxygen header and copyright notice so the copyright notice is - not included in the Doxygen output. + /* + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (C) <FIRST YEAR>, <LAST YEAR> <COPYRIGHT HOLDER> + * + * 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. + */ + + /** + * @file + * + * @ingroup TheGroupForThisFile + * + * @brief Short "Table of Contents" Description of File Contents + * + * A short description of the purpose of this file. + */ + + #if HAVE_CONFIG_H + #include "config.h" + #endif + + #include <foo/bar/baz.h> + + /* Definitions, etc. */ + +Python File Template +-------------------- + +Use the following template for Python source files and other files which accept +a ``#``-style comment block. For the <FIRST YEAR>, <LAST YEAR>, and +<COPYRIGHT HOLDER> placeholders see :ref:`FileHeaderCopyright`. + +.. code-block:: c -* The copyright owner and specific license terms may vary. + #!/usr/bin/env python -.. COMMENT: TBD - TBD Add link to license requirements section and show variant licenses. + # SPDX-License-Identifier: BSD-2-Clause + # + # Copyright (C) <FIRST YEAR>, <LAST YEAR> <COPYRIGHT HOLDER> + # + # 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. -- 2.16.4 _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
