Re: [Wikitech-l] @author annotations in files in the mediawiki codebase

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: 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