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

[Christian Mauderer]

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.

* 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?

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