Re: [PATCH] RFC: add MAINTAINERS file

[Junio C Hamano <gitster@pobox.com>]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> This patch is designed to spur discussion about adding an official
> MAINTAINERS file to our project. The hope is that it could be used as a
> reference in (at least) the following scenarios:
>
>   (1) [CC list] patch authors want to know who to CC on their
>       submissions, without resorting to git-blame-level of precision;
>
>   (2) [escalation path] patch authors have been waiting 1+ weeks for
>       review comments, but are not sure who to escalate to (other than
>       Junio);
>
>   (3) [status tracking] record former maintainers/reviewers who are now
>       inactive.
>
> In addition having a MAINTAINERS file could give a more official sense
> of ownership in the codebase.

OK.  They are understandable goals.

As to the format of the actual file, I do not have much opinion.
What works for the kernel may or may not work for us, as the project
size is very different, but I am fairly confident that we can agree
on something usable.

I am more worried about how the file is used and maintained.  Some
things to think about while in the "spurred discussion" I can think
of are:

 - Is the project big enough to require this (especially for the
   purpose of (1)), or would

   $ git shortlog -n --no-merges --since=24.months -- path-to-file

   be sufficient and more importantly the value that it will keep
   current automatically outweigh the benefit of having this file
   that can go stale?  To answer this question, we'd need to know
   the turnover rates of past project contributors, of course.  If
   it is too high, having such a list may help for (1) and (3)
   above.

 - How binding is it for a contributor to be on this list as an area
   expert?  Will there be concrete "expected response time"?  It can
   be different for each area expert, of course.  I'd expect better
   from those who work on Git as a major part of their job and
   contributes some part of their work product back to the upstream,
   than from folks who do Git as a hobby.  Is each contributer
   expected to volunteer to be on this list, with self declared
   service level target?

 - With many good reviewer candidates being employed in companies
   and doing Git as part of their job, how would we handle folks
   getting transferred out of the Git ecosystem?  Unlike in a
   corporate environment, nominating successors who have no track
   record in the community by the current area expert would not work
   at all.  The successors themselves have to earn respect by
   demonstrating their own competence, which would take time.

There may be many others.

Thanks.

> The MAINTAINERS file here is stolen from the one used in the Linux
> Kernel. We do not have to follow its format at all; it is merely added
> here as a reference for comparison and prior art.
>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>     RFC: add MAINTAINERS file
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1694%2Flistx%2Fmaintainers-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1694/listx/maintainers-v1
> Pull-Request: https://github.com/git/git/pull/1694
>
>  MAINTAINERS | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 85 insertions(+)
>  create mode 100644 MAINTAINERS
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> new file mode 100644
> index 00000000000..34fa3baf3a5
> --- /dev/null
> +++ b/MAINTAINERS
> @@ -0,0 +1,85 @@
> +List of maintainers
> +===================
> +
> +Descriptions of section entries and preferred order
> +---------------------------------------------------
> +
> +	M: *Mail* patches to: FullName <address@domain>
> +	R: Designated *Reviewer*: FullName <address@domain>
> +	   These reviewers should be CCed on patches.
> +	L: *Mailing list* that is relevant to this area
> +	S: *Status*, one of the following:
> +	   Supported:	Someone is actually paid to look after this.
> +	   Maintained:	Someone actually looks after it.
> +	   Odd Fixes:	It has a maintainer but they don't have time to do
> +			much other than throw the odd patch in. See below..
> +	   Orphan:	No current maintainer [but maybe you could take the
> +			role as you write your new code].
> +	   Obsolete:	Old code. Something tagged obsolete generally means
> +			it has been replaced by a better system and you
> +			should be using that.
> +	W: *Web-page* with status/info
> +	Q: *Patchwork* web based patch tracking system site
> +	B: URI for where to file *bugs*. A web-page with detailed bug
> +	   filing info, a direct bug tracker link, or a mailto: URI.
> +	C: URI for *chat* protocol, server and channel where developers
> +	   usually hang out, for example irc://server/channel.
> +	P: *Subsystem Profile* document for more details submitting
> +	   patches to the given subsystem. This is either an in-tree file,
> +	   or a URI. See Documentation/maintainer/maintainer-entry-profile.rst
> +	   for details.
> +	T: *SCM* tree type and location.
> +	   Type is one of: git, hg, quilt, stgit, topgit
> +	F: *Files* and directories wildcard patterns.
> +	   A trailing slash includes all files and subdirectory files.
> +	   F:	drivers/net/	all files in and below drivers/net
> +	   F:	drivers/net/*	all files in drivers/net, but not below
> +	   F:	*/net/*		all files in "any top level directory"/net
> +	   One pattern per line.  Multiple F: lines acceptable.
> +	X: *Excluded* files and directories that are NOT maintained, same
> +	   rules as F:. Files exclusions are tested before file matches.
> +	   Can be useful for excluding a specific subdirectory, for instance:
> +	   F:	net/
> +	   X:	net/ipv6/
> +	   matches all files in and below net excluding net/ipv6/
> +	N: Files and directories *Regex* patterns.
> +	   N:	[^a-z]tegra	all files whose path contains tegra
> +	                        (not including files like integrator)
> +	   One pattern per line.  Multiple N: lines acceptable.
> +	   scripts/get_maintainer.pl has different behavior for files that
> +	   match F: pattern and matches of N: patterns.  By default,
> +	   get_maintainer will not look at git log history when an F: pattern
> +	   match occurs.  When an N: match occurs, git log history is used
> +	   to also notify the people that have git commit signatures.
> +	K: *Content regex* (perl extended) pattern match in a patch or file.
> +	   For instance:
> +	   K: of_get_profile
> +	      matches patches or files that contain "of_get_profile"
> +	   K: \b(printk|pr_(info|err))\b
> +	      matches patches or files that contain one or more of the words
> +	      printk, pr_info or pr_err
> +	   One regex pattern per line.  Multiple K: lines acceptable.
> +
> +Maintainers List
> +----------------
> +
> +.. note:: When reading this list, please look for the most precise areas
> +          first. When adding to this list, please keep the entries in
> +          alphabetical order.
> +
> +3C59X NETWORK DRIVER
> +M:	Steffen Klassert <klassert@kernel.org>
> +L:	netdev@vger.kernel.org
> +S:	Odd Fixes
> +F:	Documentation/networking/device_drivers/ethernet/3com/vortex.rst
> +F:	drivers/net/ethernet/3com/3c59x.c
> +
> +...
> +
> +THE REST
> +M:	Linus Torvalds <torvalds@linux-foundation.org>
> +L:	linux-kernel@vger.kernel.org
> +S:	Buried alive in reporters
> +T:	git git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
> +F:	*
> +F:	*/
>
> base-commit: 11c821f2f2a31e70fb5cc449f9a29401c333aad2