Re: [RFC 3/4] Documentation: move dma-buf documentation to rst

[Jani Nikula]

On Thu, 11 Aug 2016, Sumit Semwal <sumit.semwal@xxxxxxxxxx> wrote:
> diff --git a/Documentation/dma-buf/guide.rst b/Documentation/dma-buf/guide.rst
> new file mode 100644
> index 000000000000..fd3534fdccb3
> --- /dev/null
> +++ b/Documentation/dma-buf/guide.rst
> @@ -0,0 +1,503 @@
> +
> +.. _dma-buf-guide:
> +
> +============================
> +DMA Buffer Sharing API Guide
> +============================
> +
> +Sumit Semwal - sumit.semwal@xxxxxxxxxx, sumits@xxxxxxxxxx

Please use the format

:author: Sumit Semwal <sumit.semwal@xxxxxxxxxx>

---

While on this subject, please excuse me for hijacking the thread a bit.

Personally, I believe it would be better to leave out authorship notes
from documentation and source files in collaborative projects. Of
course, it is only fair that people who deserve credit get the
credit. Listing the authors in the file is often the natural thing to
do, and superficially seems fair.

However, when do you add more names to the list? When has someone
contributed enough to warrant that? Is it fair that the original authors
keep getting the credit for the contributions of others? After a while,
perhaps there is next to nothing left of the original contributions, but
the bar is really high for removing anyone from the authors. Listing the
authors gives the impression this is *their* file, while everyone should
feel welcome to contribute, and everyone who contributes should feel
ownership.

IMHO we would be better off using just the git history for the credits.


BR,
Jani.


PS. I am no saint here, I've got a couple of authors lines myself. I
promise not to add more. I certainly won't chastise anyone for adding
theirs.


-- 
Jani Nikula, Intel Open Source Technology Center