Update #3053. --- v2: Clarify COPYING update and placeholders.
eng/coding-file-hdr.rst | 169 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 139 insertions(+), 30 deletions(-) diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst index c724c5d..e6ebaf1 100644 --- a/eng/coding-file-hdr.rst +++ b/eng/coding-file-hdr.rst @@ -1,45 +1,154 @@ .. 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 +.. 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. It 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: +.. code-block:: none + + 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. + +.. _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. Please +note that there is no verbatim copy of the BSD-2-Clause license included. The +license is specified by the SPDX Licence Identifier. + +.. code-block:: none + + /* + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (C) <FIRST YEAR>, <LAST YEAR> <COPYRIGHT HOLDER> + */ + +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. + +Header File Template +-------------------- + +Use the following guidelines and template for 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> + */ + + /** + * @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 - /* - * 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. - */ + #include <foo/bar/xyz.h> + #ifdef __cplusplus + extern "C" { + #endif + + /* Declarations, defines, macros, inline functions, etc. */ + + #ifdef __cplusplus + } + #endif + + #endif /* _FOO_BAR_BAZ_H */ + +Source File Template +-------------------- + +Use the following template for 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 -* Use exactly one blank line between the Doxygen header and copyright notice. - Leave the first line of the copyright notice blank. + /* + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (C) <FIRST YEAR>, <LAST YEAR> <COPYRIGHT HOLDER> + */ -* Separate the Doxygen header and copyright notice so the copyright notice is - not included in the Doxygen output. + #if HAVE_CONFIG_H + #include "config.h" + #endif -* The copyright owner and specific license terms may vary. + #include <foo/bar/baz.h> -.. COMMENT: TBD - TBD Add link to license requirements section and show variant licenses. + /* Definitions, etc. */ -- 2.16.4 _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
