[PATCH rtems-docs] eng: Add rules for attribution
Joel Sherrill
joel at rtems.org
Tue Sep 28 12:48:51 UTC 2021
On Tue, Sep 28, 2021, 1:40 AM Christian MAUDERER <
christian.mauderer at embedded-brains.de> wrote:
> 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.
>
I usually use the word sponsored. Support implies commercial activities the
way I/we tend to use it.
> >
> >
> > 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