On Jun 13, 2017 6:24 AM, "Gergo Tisza" <gtisza(a)wikimedia.org> wrote:
On Tue, Jun 13, 2017 at 7:11 AM, Subramanya Sastry <ssastry(a)wikimedia.org>
wrote:
I find these annotations misleading and wonder why
they exist and what
purpose they serve.
It can sometimes tell you whom to ask for advice or reviews. (git log would
too but it's more effort.)
For the record (since one of my patches was specifically mentioned) Gergo's
reason matches mine. This is common (if informal) practice for a number of
open source software projects---a way to easily indicate the original
author of the code, as a pointer to who to ask if you've got questions
about it. The informal practice is to add yourself to the list if you
undertake any major change or refactoring, some contribution which would
make you "at least as good a person to ask questions of" for some part of
the file.
It's admittedly imperfect. We have a list of module owners on-wiki which
is "better" but much harder to find. And as Gergo says, `git log` is more
authoritative, although anyone who has tried this sort of archeology knows
that it can be exhausting to scroll through the long history of trivial
fixes, language updates, code style tweaks, etc to find the few people who
made significant contributions.
In my experience a central CREDITS file is actually worse for code
archeology (although perhaps meets certain legal obligations better).
Because it is separate from the file itself, it is harder to find (and if
it's hard to find, we might as well use our on-wiki list), and less likely
to be kept up to date. I'm listed in the Linux kernel CREDITS file for
several projects which have subsequently been completely removed from the
source tree! If you keep @authors in the source file at least it stands a
better shot at being removed if/when the code is, or of surviving a
renaming or refactoring if still relevant. (The linux kernel has both
standalone CREDITS akin to our on-wiki list of module maintainers as well
as in-flight authorship info, and I still get occasional inquiries from
folks diving into the pty code for the first time.)
If we were to make a change, I'd suggest including an @authors tag in each
file explicitly naming the appropriate on-wiki module owners list, ie:
@author
https://meta/wiki/Module_owners#Parser
Or what have you. Simply removing the @author tag seems like it is
removing a resource for new contributors with no replacement.
--scott