[PATCH rtems-docs] eng: Add rules for attribution
Christian MAUDERER
christian.mauderer at embedded-brains.de
Tue Sep 28 06:40:47 UTC 2021
Hello Joel,
Am 28.09.21 um 01:12 schrieb Joel Sherrill:
> 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.
But maybe an important extension. Should we replace "sponsored" with
"sponsored or supported"? That would allow to mention anyone who helps
in any way, regardless whether it's financial, with information, with
hobby time or with whatever else.
>
>
> On Mon, Sep 27, 2021, 9:49 AM Christian Mauderer
> <christian.mauderer at embedded-brains.de
> <mailto: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
> <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
So for documentation it would be one SUPPORTERS file that isn't
processed in any way?
>
>
> * 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
> <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?
>
Hm. Good questions.
What I wanted to tell is: Do we need to document who allowed us to
mention the company name?
"git blame" won't tell the same. It would only tell who added the line
"sponsored by Some Company". In most cases that will be the developer
working on it and not the one from "Some Company" who said that we can
add the name.
You are right that a manager without git has problems adding the signed
off line in the "official" git form. But git comments are free text
anyway. I think a "signed off" line is based on trust like everything
else in git. It more or less means: The one who pushes the patch has
some when asked the person whether the patch is OK. We can also add it
as a free text comment like "Some Company added with friendly permission
by Some Person".
I'm not sure whether it's an advantage to add something like that or
whether it's unnecessary bureaucracy.
Best regards
Christian
>
> 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 <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 <mailto:devel at rtems.org>
> http://lists.rtems.org/mailman/listinfo/devel
> <http://lists.rtems.org/mailman/listinfo/devel>
>
--
--------------------------------------------
embedded brains GmbH
Herr Christian MAUDERER
Dornierstr. 4
82178 Puchheim
Germany
email: christian.mauderer at embedded-brains.de
phone: +49-89-18 94 741 - 18
fax: +49-89-18 94 741 - 08
Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/
More information about the devel
mailing list