[PATCH rtems-docs] eng: Add rules for attribution

Mon Sep 27 23:12:50 UTC 2021

The Microblaze port is interesting for attribution. I did initial work on
it. Hesham added to that and got Hello on a board. Alex is close to
submitting the port in a nice state.

This is almost seven years across three developers.. The original work
predates source code reorganisation. Alex deleted the autoconf support and
created waf. Hesham and I agreed to convert to BSD-2.

When submitted, we decided it was best for Alex to submit a Joel patch,
then Hesham, then Alex to finish it off. This keeps git blame working.

Not quite the same topic but related to credit due.

On Mon, Sep 27, 2021, 9:49 AM Christian Mauderer <
christian.mauderer at embedded-brains.de> wrote:

> This adds some rules how an attribution for sponsored development should
> look like.
> ---
>
> Note: This patch is more or less an early draft. See the following
> discussion
> for more background:
>
> https://lists.rtems.org/pipermail/devel/2021-September/069465.html
>
> Points that need discussion:
>
> * Are there some areas where we don't want to have attribution lines (Chris
>   asked about score in the linked discussion). From my point of view: If
> there
>   is a big contribution and the sponsor wants his name in the (changed)
> files,
>   that's OK.
>
> * Do we want attributions in documentation sources? I'm not sure whether
> they
>   might end in HTML comments in the distributed documentation.
>

So far, not enough small has been submitted to matter.

I'm happy with a master list

>
> * What kind of format do we want in the documentation? Restructured Text
>   documentation suggests that the two dots should be on a separate line to
> avoid
>   interpreting the comment as directive:
>
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#comments
>
> * Do we need some kind of "signed off" from the sponsor (or similar) in the
>   commits that add attribution so that we can later tell who said that it
> is OK
>   that we mention the sponsor?
>

We've done this on trust for a long time but wouldn't git blame tell us the
same? If it is a manager without git, then what?

> I'm sure there are some more points. Please feel free to ask. Again: This
> is a
> draft.
>
> Best regards
>
> Christian
>
>  eng/coding-file-hdr.rst | 48 +++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 48 insertions(+)
>
> diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst
> index 3167670..da6f702 100644
> --- a/eng/coding-file-hdr.rst
> +++ b/eng/coding-file-hdr.rst
> @@ -2,6 +2,7 @@
>
>  .. Copyright (C) 2018, 2020 embedded brains GmbH (
> http://www.embedded-brains.de)
>  .. Copyright (C) 2018, 2020 Sebastian Huber
> +.. Copyright (C) 2021 Christian Mauderer
>
>  .. _FileTemplates:
>
> @@ -74,6 +75,28 @@ 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.
>
> +.. _FileAttributionSponsor:
> +
> +Attribution for Sponsored Development
> +-------------------------------------
> +
> +A lot of development in RTEMS is sponsored by some users. If the sponsor
> wants
> +to be mentioned in the code, apply the following rules:
> +
> +* The attribution has to be a separate comment block below the copyright
> block.
> +
> +* Only the name of the sponsoring company / person should be mentioned. No
> +  contact details like URLs, email, phone numbers or street addresses
> should be
> +  added.
> +
> +* To avoid unnecessary commits, the name of a sponsor is not updated if
> (for
> +  example) the name of a company changes. The only reasonable change
> would be if
> +  a sponsor continues to pay for bigger changes in that file anyway.
> +
> +* Sponsor names are only added to files which contain relevant amounts of
> +  sponsored work. As a rule of thumb: If the work justifies adding a
> copyright
> +  line, it also justifies adding a sponsor line.
> +
>  .. _CCXXHeaderFileTemplate:
>
>  C/C++ Header File Template
> @@ -96,6 +119,8 @@ Use the following guidelines and template for C and C++
> header files (here
>  * Separate the Doxygen comment block from the copyright and license, so
> that
>    the copyright and license information is not included in the Doxygen
> output.
>
> +* If there is a sponsor: Add it as a separate comment block.
> +
>  * For C++ header files discard the ``extern "C"`` start and end sections.
>
>  .. code-block:: c
> @@ -137,6 +162,12 @@ Use the following guidelines and template for C and
> C++ header files (here
>       * POSSIBILITY OF SUCH DAMAGE.
>       */
>
> +    /*
> +     * Initial foo bar implementation sponsored by Example Inc.
> +     *
> +     * Baz feature sponsored by Some LLC.
> +     */
> +
>      #ifndef _FOO_BAR_BAZ_H
>      #define _FOO_BAR_BAZ_H
>
> @@ -204,6 +235,12 @@ and <COPYRIGHT HOLDER> placeholders see
> :ref:`FileHeaderCopyright`.
>       * POSSIBILITY OF SUCH DAMAGE.
>       */
>
> +    /*
> +     * Initial foo bar implementation sponsored by Example Inc.
> +     *
> +     * Baz feature sponsored by Some LLC.
> +     */
> +
>      #ifdef HAVE_CONFIG_H
>      #include "config.h"
>      #endif
> @@ -251,6 +288,10 @@ block. RTEMS uses ``"""`` for Python docstrings.
>      # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
> OF THE
>      # POSSIBILITY OF SUCH DAMAGE.
>
> +    # Initial foo bar implementation sponsored by Example Inc.
> +    #
> +    # Baz feature sponsored by Some LLC.
> +
>  If the Python source file is a command line command add the following as
> the
>  first line of the file:
>
> @@ -302,6 +343,10 @@ accept a ``#``-style comment block. For the <FIRST
> YEAR>, <LAST YEAR>, and
>      # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
> OF THE
>      # POSSIBILITY OF SUCH DAMAGE.
>
> +    # Initial foo bar implementation sponsored by Example Inc.
> +    #
> +    # Baz feature sponsored by Some LLC.
> +
>  reStructuredText File Template
>  ------------------------------
>
> @@ -314,3 +359,6 @@ Use the following template for reStructuredText (reST)
> source files.  For the
>      .. SPDX-License-Identifier: CC-BY-SA-4.0
>
>      .. Copyright (C) <FIRST YEAR>, <LAST YEAR> <COPYRIGHT HOLDER>
> +
> +    ..
> +       Documentation of foo bar feature sponsored by Example Inc.
> --
> 2.31.1
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>