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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <87o9zngji9.fsf@intel.com>
Date:   Wed, 04 Jan 2017 13:19:26 +0200
From:   Jani Nikula <jani.nikula@...ux.intel.com>
To:     Sebastian Andrzej Siewior <bigeasy@...utronix.de>
Cc:     linux-kernel@...r.kernel.org, tglx@...utronix.de, rt@...utronix.de,
        Jonathan Corbet <corbet@....net>,
        Mauro Carvalho Chehab <mchehab@...nel.org>,
        Rusty Russell <rusty@...tcorp.com.au>,
        Srivatsa Vaddagiri <vatsa@...ibm.com>,
        Ashok Raj <ashok.raj@...el.com>,
        Joel Schopp <jschopp@...tin.ibm.com>, linux-doc@...r.kernel.org
Subject: Re: [PATCH] Documentation: Update CPU hotplug and move it to core-api

On Wed, 04 Jan 2017, Sebastian Andrzej Siewior <bigeasy@...utronix.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@...utronix.de>,
>> > +          Rusty Russell <rusty@...tcorp.com.au>,
>> > +          Srivatsa Vaddagiri <vatsa@...ibm.com>,
>> > +          Ashok Raj <ashok.raj@...el.com>,
>> > +          Joel Schopp <jschopp@...tin.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