On Wed, 04 Jan 2017, Sebastian Andrzej Siewior <bigeasy@xxxxxxxxxxxxx> 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@xxxxxxxxxxxxx>, >> > + Rusty Russell <rusty@xxxxxxxxxxxxxxx>, >> > + Srivatsa Vaddagiri <vatsa@xxxxxxxxxx>, >> > + Ashok Raj <ashok.raj@xxxxxxxxx>, >> > + Joel Schopp <jschopp@xxxxxxxxxxxxxx> >> >> 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
