[PATCH] eng: Rework file template section

Wed Feb 19 07:54:03 UTC 2020

On 19/2/20 6:07 pm, Sebastian Huber wrote:
> Update #3053.
> ---
>  eng/coding-file-hdr.rst | 161 +++++++++++++++++++++++++++++++++++++++---------
>  1 file changed, 131 insertions(+), 30 deletions(-)
> 
> diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst
> index c724c5d..788da95 100644
> --- a/eng/coding-file-hdr.rst
> +++ b/eng/coding-file-hdr.rst
> @@ -1,45 +1,146 @@
>  .. 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.
> +
> +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 if the top-level :file:`COPYING` file needs an update.

What needs to be updated? I think there needs to more detail here, ie add your
name etc.

> +
> +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.
> +
> +* 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
> +
> +    #include <foo/bar/xyz.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.
> -   */
> +    #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>`):
> +
> +.. 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. */
> 

I think "<FIRST YEAR>", "<LAST YEAR>" and "<COPYRIGHT HOLDER>" need to be
explained. For example "Use your real name, that is your legal name." or "Use a
name and/or email address" or something else.

Chris