[PATCH v3] eng: Rework file template section

Sebastian Huber sebastian.huber at embedded-brains.de
Thu Feb 20 08:20:30 UTC 2020


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



More information about the devel mailing list