[Buildroot] Buildroot manual: author list

[Buildroot] Buildroot manual: author list

[Thomas De Schampheleire]

Hi,

Currently, the Buildroot manual contains the following in the introduction:

"Buildroot usage and documentation by Thomas Petazzoni. Contributions
from Karsten Kruse, Ned Ludd, Martin Herren and others."

This text (besides the 'and others' part) dates from the initial
version of the documentation, commit
32fcf718f82c241e890af8c7ccc10ef6c438331a, back in 2004.
(http://git.buildroot.org/buildroot/commit/?id=32fcf7)

In these 10 years, the manual has expanded a lot, and many people have
contributed. A shortlog of the original location docs/buildroot.html
(at commit 41c1cb44cd60819f8ba20024e23e431c00b279d7)


$ git shortlog -sn  docs/buildroot.html
    31  Thomas Petazzoni
    28  Peter Korsgaard
    15  Bernhard Reutner-Fischer
    11  Ulf Samuelsson
     6  Mike Frysinger
     3  Bj?rn Forsman
     3  Martin Banky
     1  Daniel Mack
     1  Eric Andersen
     1  Gustavo Zacarias
     1  Lionel Landwerlin
     1  Luca Ceresoli
     1  Peter Huewe
     1  Yegor Yefremov
     1  grante

and a shortlog of the new directory docs/manual (at current master):

$ git shortlog -sn  docs/manual
    49  Thomas Petazzoni
    40  Samuel Martin
    35  Thomas De Schampheleire
    28  Yann E. MORIN
    15  Jerzy Grzegorek
    12  Arnout Vandecappelle (Essensium/Mind)
    11  Peter Korsgaard
     4  Samuel MARTIN
     4  Simon Dawson
     3  Arnout Vandecappelle
     3  Francois Perrad
     3  Luca Ceresoli
     3  Maxime Hadjinlian
     3  Maxime Ripard
     3  Nathan Lynch
     3  Ryan Barnett
     3  Stephan Hoffmann
     3  eric.le.bihan.dev at free.fr
     2  Gustavo Zacarias
     2  Mischa Jonker
     2  Shawn Landden
     1  A.R.D
     1  Alexandre Belloni
     1  Alvaro G. M
     1  Davide Viti
     1  Fabio Porcedda
     1  J?r?me Pouiller
     1  Marek Belisko
     1  Ralph Siemsen
     1  Shawn J. Goff
     1  Sonic Zhang
     1  Spenser Gilliland
     1  Stefan Fr?berg
     1  Tilman Keskin?z
     1  Trevor Woerner
     1  Tzu-Jung Lee
     1  Vinicius Tinti


My feeling is that the current listing of authors is not correct
towards all these other people. There are at least three alternatives
to do something about this:

a. replace the author reference in buildroot by a reference to 'the
Buildroot developers' and let interested people look up the real list
in git.

b. expand the list with some of the major contributors to the manual,
based on the shortlogs above

c. add an appendix with a generated list (shortlog) of authors, which
is then complete and up-to-date.


I'm leaning more to a. or b. than to c.
The advantage of a. over b. is that there is no discussion about whose
name should be in the list (where to draw the line), while b. has the
advantage of giving more explicit credit.

The purpose of this mail is to request your feedback about this.

Thanks,
Thomas

[Buildroot] Buildroot manual: author list

[Yann E. MORIN]

Thomas, All,

On 2014-05-27 21:22 +0200, Thomas De Schampheleire spake thusly:
> Currently, the Buildroot manual contains the following in the introduction:
> 
> "Buildroot usage and documentation by Thomas Petazzoni. Contributions
> from Karsten Kruse, Ned Ludd, Martin Herren and others."
[--SNIP--]
> My feeling is that the current listing of authors is not correct
> towards all these other people. There are at least three alternatives
> to do something about this:
> 
> a. replace the author reference in buildroot by a reference to 'the
> Buildroot developers' and let interested people look up the real list
> in git.
> 
> b. expand the list with some of the major contributors to the manual,
> based on the shortlogs above
> 
> c. add an appendix with a generated list (shortlog) of authors, which
> is then complete and up-to-date.
> 
> 
> I'm leaning more to a. or b. than to c.
> The advantage of a. over b. is that there is no discussion about whose
> name should be in the list (where to draw the line), while b. has the
> advantage of giving more explicit credit.

As I suggested on IRC: what about a.+c.? Just change the introduction to:

    Buildroot manual by the Buildroot developers, see xref:credits[].

and add the appendix 'credits' at the end of the manual?

Otherwise, I'd go for just a.

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] Buildroot manual: author list

[Thomas De Schampheleire]

On Tue, May 27, 2014 at 9:36 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Thomas, All,
>
> On 2014-05-27 21:22 +0200, Thomas De Schampheleire spake thusly:
>> Currently, the Buildroot manual contains the following in the introduction:
>>
>> "Buildroot usage and documentation by Thomas Petazzoni. Contributions
>> from Karsten Kruse, Ned Ludd, Martin Herren and others."
> [--SNIP--]
>> My feeling is that the current listing of authors is not correct
>> towards all these other people. There are at least three alternatives
>> to do something about this:
>>
>> a. replace the author reference in buildroot by a reference to 'the
>> Buildroot developers' and let interested people look up the real list
>> in git.
>>
>> b. expand the list with some of the major contributors to the manual,
>> based on the shortlogs above
>>
>> c. add an appendix with a generated list (shortlog) of authors, which
>> is then complete and up-to-date.
>>
>>
>> I'm leaning more to a. or b. than to c.
>> The advantage of a. over b. is that there is no discussion about whose
>> name should be in the list (where to draw the line), while b. has the
>> advantage of giving more explicit credit.
>
> As I suggested on IRC: what about a.+c.? Just change the introduction to:
>
>     Buildroot manual by the Buildroot developers, see xref:credits[].
>
> and add the appendix 'credits' at the end of the manual?

Sorry that this wasn't clear. With c. I did mean a+c as you showed above.
Although I'm certainly not against it, I (personally) don't
particularly see a need to add an explicit list for the manual. If
we'd do this, then it makes sense to also do it for the 'real'
contributions. But such info can already be obtained from git or
Ohloh.

Best regards,
Thomas

[Buildroot] Buildroot manual: author list

[Peter Korsgaard]

>>>>> "Yann" == Yann E MORIN <yann.morin.1998@free.fr> writes:

Hi,

 >> I'm leaning more to a. or b. than to c.
 >> The advantage of a. over b. is that there is no discussion about whose
 >> name should be in the list (where to draw the line), while b. has the
 >> advantage of giving more explicit credit.

 > As I suggested on IRC: what about a.+c.? Just change the introduction to:

 >     Buildroot manual by the Buildroot developers, see xref:credits[].

 > and add the appendix 'credits' at the end of the manual?

I would also suggest we go for a (unless any of the people explictly
listed would disagree). We don't list authorship anywhere else (E.G. in
the .mk files) in Buildroot, and it sounds like a pain to maintain such
a list and decide what a 'major contribution' is.

Thomas (Petazzoni), what do you say?

-- 
Bye, Peter Korsgaard

[Buildroot] Buildroot manual: author list

[Yann E. MORIN]

Peter, All,

On 2014-05-27 21:45 +0200, Peter Korsgaard spake thusly:
> >>>>> "Yann" == Yann E MORIN <yann.morin.1998@free.fr> writes:
>  >> I'm leaning more to a. or b. than to c.
>  >> The advantage of a. over b. is that there is no discussion about whose
>  >> name should be in the list (where to draw the line), while b. has the
>  >> advantage of giving more explicit credit.
> 
>  > As I suggested on IRC: what about a.+c.? Just change the introduction to:
> 
>  >     Buildroot manual by the Buildroot developers, see xref:credits[].
> 
>  > and add the appendix 'credits' at the end of the manual?
> 
> I would also suggest we go for a (unless any of the people explictly
> listed would disagree). We don't list authorship anywhere else (E.G. in
> the .mk files) in Buildroot, and it sounds like a pain to maintain such
> a list and decide what a 'major contribution' is.

Oh, we'd maintain the same way we maintain the list of packages: with a
little bit of scripting and a make target in docs/manual/manual.mk.

But I'm fine with just a., too. I just misunderstood Thomas DS'
c-suggestion.

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] Buildroot manual: author list

[Arnout Vandecappelle]

On 27/05/14 21:45, Peter Korsgaard wrote:
>>>>>> "Yann" == Yann E MORIN <yann.morin.1998@free.fr> writes:
> 
> Hi,
> 
>  >> I'm leaning more to a. or b. than to c.
>  >> The advantage of a. over b. is that there is no discussion about whose
>  >> name should be in the list (where to draw the line), while b. has the
>  >> advantage of giving more explicit credit.
> 
>  > As I suggested on IRC: what about a.+c.? Just change the introduction to:
> 
>  >     Buildroot manual by the Buildroot developers, see xref:credits[].
> 
>  > and add the appendix 'credits' at the end of the manual?
> 
> I would also suggest we go for a (unless any of the people explictly
> listed would disagree). We don't list authorship anywhere else (E.G. in
> the .mk files) in Buildroot, and it sounds like a pain to maintain such
> a list and decide what a 'major contribution' is.

 I agree with this. If we want to list contributors, it's more relevant to do
that for the entire codebase than just for the manual.

 On a side note however: Karsten Kruse, Ned Ludd, Martin Herren are *not* in the
shortlog of buildroot.html!

 Regards,
 Arnout

> 
> Thomas (Petazzoni), what do you say?
> 


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7CB5 E4CC 6C2E EFD4 6E3D A754 F963 ECAB 2450 2F1F

[Buildroot] Buildroot manual: author list

[Thomas Petazzoni]

Dear Thomas De Schampheleire,

On Tue, 27 May 2014 21:22:27 +0200, Thomas De Schampheleire wrote:

> a. replace the author reference in buildroot by a reference to 'the
> Buildroot developers' and let interested people look up the real list
> in git.

This seems to be the right thing to do, IMO. It's the simplest thing,
and it's also what we already do for the rest of the Buildroot codebase.

Best regards,

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com