Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1550531 > unrolled thread

Re: [PATCH] Documentation: Update CPU hotplug and move it to core-api

Back to article view | Back to linux.kernel

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Re: [PATCH] Documentation: Update CPU hotplug and move it to core-api Sebastian Andrzej Siewior <bigeasy@linutronix.de> - 2017-01-04 10:10 +0100
    Re: [PATCH] Documentation: Update CPU hotplug and move it to core-api Jani Nikula <jani.nikula@linux.intel.com> - 2017-01-04 12:30 +0100

#1550531 — Re: [PATCH] Documentation: Update CPU hotplug and move it to core-api

On 2016-12-23 10:03:09 [+0200], Jani Nikula wrote:
> > --- /dev/null
> > +++ b/Documentation/core-api/cpu_hotplug.rst
> > @@ -0,0 +1,372 @@
> > +=========================
> > +CPU hotplug in the Kernel
> > +=========================
> > +
> > +:Date: December, 2016
> > +:Author: Sebastian Andrzej Siewior <bigeasy@linutronix.de>,
> > +          Rusty Russell <rusty@rustcorp.com.au>,
> > +          Srivatsa Vaddagiri <vatsa@in.ibm.com>,
> > +          Ashok Raj <ashok.raj@intel.com>,
> > +          Joel Schopp <jschopp@austin.ibm.com>
> 
> Just a drive-by comment, does that do what you want? You might want to
> see if adding one :Author: line per author produces better results.

I see an Author: line for each author, I like better the way it is.

> That said, I think git will do a better job of maintaining both the date
> and the authorship.

If you see the generated html output in your browser you don't have git
around to check the date or the Author. The date should help you to keep
track of the latest version. As for the Author, git would only show me
as the author but I did not write everything myself. Some parts are
still from old documentation.

> BR,
> Jani.

Sebastian

[toc] | [next] | [standalone]

#1550670

On Wed, 04 Jan 2017, Sebastian Andrzej Siewior <bigeasy@linutronix.de> wrote:
> On 2016-12-23 10:03:09 [+0200], Jani Nikula wrote:
>> > --- /dev/null
>> > +++ b/Documentation/core-api/cpu_hotplug.rst
>> > @@ -0,0 +1,372 @@
>> > +=========================
>> > +CPU hotplug in the Kernel
>> > +=========================
>> > +
>> > +:Date: December, 2016
>> > +:Author: Sebastian Andrzej Siewior <bigeasy@linutronix.de>,
>> > +          Rusty Russell <rusty@rustcorp.com.au>,
>> > +          Srivatsa Vaddagiri <vatsa@in.ibm.com>,
>> > +          Ashok Raj <ashok.raj@intel.com>,
>> > +          Joel Schopp <jschopp@austin.ibm.com>
>> 
>> Just a drive-by comment, does that do what you want? You might want to
>> see if adding one :Author: line per author produces better results.
>
> I see an Author: line for each author, I like better the way it is.
>
>> That said, I think git will do a better job of maintaining both the date
>> and the authorship.
>
> If you see the generated html output in your browser you don't have git
> around to check the date or the Author. The date should help you to keep
> track of the latest version. As for the Author, git would only show me
> as the author but I did not write everything myself. Some parts are
> still from old documentation.

Just to be clear, I don't really care about this file specifically one
way or the other. Do as you wish, and please don't let my comments block
you.

---

In general, I don't think maintaining either the date or the authors
manually is a good idea. This applies for both documentation and source
code.

The obvious downside is that updating them will be overlooked and
forgotten. Arguably not having them at all is better than having
incorrect or stale information (when the accurate information can be
retrieved from git).

Perhaps we could add more automatically updated metadata to the
generated documentation. We could even add the date from git if we
really wanted to. But do we? The generated documentation already
includes the kernel version, is that not enough?

Even when people do remember to update the fields, they're faced with a
dilemma: Do their changes warrant an update in date or adding themselves
as author? Are the changes significant enough? This is completely
subjective. What if there have been bigger changes by others without
updates to authors? Should you remove authors when their contributions
have been long since been removed or rewritten, and forgotten, and don't
have any relevance to the current text?

I think listing authors in files, whether they're text or source code,
in collaborative projects, is counter-productive. The best possible end
result, not the promotion of individuals, should be the shared goal. No
contributor should feel that their contribution promotes the people in
authors rather than improves the end result. No contributor should shy
away from updating a file because it seems to be "owned" by someone. Of
course, credit to whom credit is due, but in an objective and fair
manner.

I argue that git log and blame are objective, and the history is all
there for anyone that cares to look. It's not without flaws, as you
point out, but I think it's superior to maintaining authors
manually. (Copyright notices may need to be updated in the files, but
they could be in reStructuredText comments, not unlike in source code.)


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web