{"thread":{"id":"61185","subject":"[PATCH] RFC: add MAINTAINERS file","startedAt":"2024-03-23T03:27:44Z","lastAt":"2024-04-04T00:47:33Z","messageCount":23,"participants":["Linus Arver via GitGitGadget","Junio C Hamano","Linus Arver","Taylor Blau","Patrick Steinhardt","Eric Sunshine"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"491289","messageId":"pull.1694.git.git.1711164460562.gitgitgadget@gmail.com","threadId":"61185","inReplyTo":null,"subject":"[PATCH] RFC: add MAINTAINERS file","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-03-23T03:27:40Z","receivedAt":"2024-03-23T03:27:44Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThis patch is designed to spur discussion about adding an official\nMAINTAINERS file to our project. The hope is that it could be used as a\nreference in (at least) the following scenarios:\n\n (1) [CC list] patch authors want to know who to CC on their\n submissions, without resorting to git-blame-level of precision;\n\n (2) [escalation path] patch authors have been waiting 1+ weeks for\n review comments, but are not sure who to escalate to (other than\n Junio);\n\n (3) [status tracking] record former maintainers/reviewers who are now\n inactive.\n\nIn addition having a MAINTAINERS file could give a more official sense\nof ownership in the codebase.\n\nThe MAINTAINERS file here is stolen from the one used in the Linux\nKernel. We do not have to follow its format at all; it is merely added\nhere as a reference for comparison and prior art.\n\nSigned-off-by: Linus Arver \n---\n RFC: add MAINTAINERS file\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1694%2Flistx%2Fmaintainers-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1694/listx/maintainers-v1\nPull-Request: https://github.com/git/git/pull/1694\n\n MAINTAINERS | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++\n 1 file changed, 85 insertions(+)\n create mode 100644 MAINTAINERS\n\ndiff --git a/MAINTAINERS b/MAINTAINERS\nnew file mode 100644\nindex 00000000000..34fa3baf3a5\n--- /dev/null\n+++ b/MAINTAINERS\n@@ -0,0 +1,85 @@\n+List of maintainers\n+===================\n+\n+Descriptions of section entries and preferred order\n+---------------------------------------------------\n+\n+\tM: *Mail* patches to: FullName \n+\tR: Designated *Reviewer*: FullName \n+\t These reviewers should be CCed on patches.\n+\tL: *Mailing list* that is relevant to this area\n+\tS: *Status*, one of the following:\n+\t Supported:\tSomeone is actually paid to look after this.\n+\t Maintained:\tSomeone actually looks after it.\n+\t Odd Fixes:\tIt has a maintainer but they don't have time to do\n+\t\t\tmuch other than throw the odd patch in. See below..\n+\t Orphan:\tNo current maintainer [but maybe you could take the\n+\t\t\trole as you write your new code].\n+\t Obsolete:\tOld code. Something tagged obsolete generally means\n+\t\t\tit has been replaced by a better system and you\n+\t\t\tshould be using that.\n+\tW: *Web-page* with status/info\n+\tQ: *Patchwork* web based patch tracking system site\n+\tB: URI for where to file *bugs*. A web-page with detailed bug\n+\t filing info, a direct bug tracker link, or a mailto: URI.\n+\tC: URI for *chat* protocol, server and channel where developers\n+\t usually hang out, for example irc://server/channel.\n+\tP: *Subsystem Profile* document for more details submitting\n+\t patches to the given subsystem. This is either an in-tree file,\n+\t or a URI. See Documentation/maintainer/maintainer-entry-profile.rst\n+\t for details.\n+\tT: *SCM* tree type and location.\n+\t Type is one of: git, hg, quilt, stgit, topgit\n+\tF: *Files* and directories wildcard patterns.\n+\t A trailing slash includes all files and subdirectory files.\n+\t F:\tdrivers/net/\tall files in and below drivers/net\n+\t F:\tdrivers/net/*\tall files in drivers/net, but not below\n+\t F:\t*/net/*\t\tall files in \"any top level directory\"/net\n+\t One pattern per line. Multiple F: lines acceptable.\n+\tX: *Excluded* files and directories that are NOT maintained, same\n+\t rules as F:. Files exclusions are tested before file matches.\n+\t Can be useful for excluding a specific subdirectory, for instance:\n+\t F:\tnet/\n+\t X:\tnet/ipv6/\n+\t matches all files in and below net excluding net/ipv6/\n+\tN: Files and directories *Regex* patterns.\n+\t N:\t[^a-z]tegra\tall files whose path contains tegra\n+\t (not including files like integrator)\n+\t One pattern per line. Multiple N: lines acceptable.\n+\t scripts/get_maintainer.pl has different behavior for files that\n+\t match F: pattern and matches of N: patterns. By default,\n+\t get_maintainer will not look at git log history when an F: pattern\n+\t match occurs. When an N: match occurs, git log history is used\n+\t to also notify the people that have git commit signatures.\n+\tK: *Content regex* (perl extended) pattern match in a patch or file.\n+\t For instance:\n+\t K: of_get_profile\n+\t matches patches or files that contain \"of_get_profile\"\n+\t K: \\b(printk|pr_(info|err))\\b\n+\t matches patches or files that contain one or more of the words\n+\t printk, pr_info or pr_err\n+\t One regex pattern per line. Multiple K: lines acceptable.\n+\n+Maintainers List\n+----------------\n+\n+.. note:: When reading this list, please look for the most precise areas\n+ first. When adding to this list, please keep the entries in\n+ alphabetical order.\n+\n+3C59X NETWORK DRIVER\n+M:\tSteffen Klassert \n+L:\tnetdev@vger.kernel.org\n+S:\tOdd Fixes\n+F:\tDocumentation/networking/device_drivers/ethernet/3com/vortex.rst\n+F:\tdrivers/net/ethernet/3com/3c59x.c\n+\n+...\n+\n+THE REST\n+M:\tLinus Torvalds \n+L:\tlinux-kernel@vger.kernel.org\n+S:\tBuried alive in reporters\n+T:\tgit git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git\n+F:\t*\n+F:\t*/\n\nbase-commit: 11c821f2f2a31e70fb5cc449f9a29401c333aad2\n-- \ngitgitgadget\n"},{"id":"491312","messageId":"xmqqsf0gvjrg.fsf@gitster.g","threadId":"61185","inReplyTo":"pull.1694.git.git.1711164460562.gitgitgadget@gmail.com","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-03-23T19:19:15Z","receivedAt":"2024-03-23T19:19:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Linus Arver via GitGitGadget\" writes:\n\n> From: Linus Arver \n>\n> This patch is designed to spur discussion about adding an official\n> MAINTAINERS file to our project. The hope is that it could be used as a\n> reference in (at least) the following scenarios:\n>\n> (1) [CC list] patch authors want to know who to CC on their\n> submissions, without resorting to git-blame-level of precision;\n>\n> (2) [escalation path] patch authors have been waiting 1+ weeks for\n> review comments, but are not sure who to escalate to (other than\n> Junio);\n>\n> (3) [status tracking] record former maintainers/reviewers who are now\n> inactive.\n>\n> In addition having a MAINTAINERS file could give a more official sense\n> of ownership in the codebase.\n\nOK. They are understandable goals.\n\nAs to the format of the actual file, I do not have much opinion.\nWhat works for the kernel may or may not work for us, as the project\nsize is very different, but I am fairly confident that we can agree\non something usable.\n\nI am more worried about how the file is used and maintained. Some\nthings to think about while in the \"spurred discussion\" I can think\nof are:\n\n - Is the project big enough to require this (especially for the\n purpose of (1)), or would\n\n $ git shortlog -n --no-merges --since=24.months -- path-to-file\n\n be sufficient and more importantly the value that it will keep\n current automatically outweigh the benefit of having this file\n that can go stale? To answer this question, we'd need to know\n the turnover rates of past project contributors, of course. If\n it is too high, having such a list may help for (1) and (3)\n above.\n\n - How binding is it for a contributor to be on this list as an area\n expert? Will there be concrete \"expected response time\"? It can\n be different for each area expert, of course. I'd expect better\n from those who work on Git as a major part of their job and\n contributes some part of their work product back to the upstream,\n than from folks who do Git as a hobby. Is each contributer\n expected to volunteer to be on this list, with self declared\n service level target?\n\n - With many good reviewer candidates being employed in companies\n and doing Git as part of their job, how would we handle folks\n getting transferred out of the Git ecosystem? Unlike in a\n corporate environment, nominating successors who have no track\n record in the community by the current area expert would not work\n at all. The successors themselves have to earn respect by\n demonstrating their own competence, which would take time.\n\nThere may be many others.\n\nThanks.\n\n> The MAINTAINERS file here is stolen from the one used in the Linux\n> Kernel. We do not have to follow its format at all; it is merely added\n> here as a reference for comparison and prior art.\n>\n> Signed-off-by: Linus Arver \n> ---\n> RFC: add MAINTAINERS file\n>\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1694%2Flistx%2Fmaintainers-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1694/listx/maintainers-v1\n> Pull-Request: https://github.com/git/git/pull/1694\n>\n> MAINTAINERS | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++\n> 1 file changed, 85 insertions(+)\n> create mode 100644 MAINTAINERS\n>\n> diff --git a/MAINTAINERS b/MAINTAINERS\n> new file mode 100644\n> index 00000000000..34fa3baf3a5\n> --- /dev/null\n> +++ b/MAINTAINERS\n> @@ -0,0 +1,85 @@\n> +List of maintainers\n> +===================\n> +\n> +Descriptions of section entries and preferred order\n> +---------------------------------------------------\n> +\n> +\tM: *Mail* patches to: FullName \n> +\tR: Designated *Reviewer*: FullName \n> +\t These reviewers should be CCed on patches.\n> +\tL: *Mailing list* that is relevant to this area\n> +\tS: *Status*, one of the following:\n> +\t Supported:\tSomeone is actually paid to look after this.\n> +\t Maintained:\tSomeone actually looks after it.\n> +\t Odd Fixes:\tIt has a maintainer but they don't have time to do\n> +\t\t\tmuch other than throw the odd patch in. See below..\n> +\t Orphan:\tNo current maintainer [but maybe you could take the\n> +\t\t\trole as you write your new code].\n> +\t Obsolete:\tOld code. Something tagged obsolete generally means\n> +\t\t\tit has been replaced by a better system and you\n> +\t\t\tshould be using that.\n> +\tW: *Web-page* with status/info\n> +\tQ: *Patchwork* web based patch tracking system site\n> +\tB: URI for where to file *bugs*. A web-page with detailed bug\n> +\t filing info, a direct bug tracker link, or a mailto: URI.\n> +\tC: URI for *chat* protocol, server and channel where developers\n> +\t usually hang out, for example irc://server/channel.\n> +\tP: *Subsystem Profile* document for more details submitting\n> +\t patches to the given subsystem. This is either an in-tree file,\n> +\t or a URI. See Documentation/maintainer/maintainer-entry-profile.rst\n> +\t for details.\n> +\tT: *SCM* tree type and location.\n> +\t Type is one of: git, hg, quilt, stgit, topgit\n> +\tF: *Files* and directories wildcard patterns.\n> +\t A trailing slash includes all files and subdirectory files.\n> +\t F:\tdrivers/net/\tall files in and below drivers/net\n> +\t F:\tdrivers/net/*\tall files in drivers/net, but not below\n> +\t F:\t*/net/*\t\tall files in \"any top level directory\"/net\n> +\t One pattern per line. Multiple F: lines acceptable.\n> +\tX: *Excluded* files and directories that are NOT maintained, same\n> +\t rules as F:. Files exclusions are tested before file matches.\n> +\t Can be useful for excluding a specific subdirectory, for instance:\n> +\t F:\tnet/\n> +\t X:\tnet/ipv6/\n> +\t matches all files in and below net excluding net/ipv6/\n> +\tN: Files and directories *Regex* patterns.\n> +\t N:\t[^a-z]tegra\tall files whose path contains tegra\n> +\t (not including files like integrator)\n> +\t One pattern per line. Multiple N: lines acceptable.\n> +\t scripts/get_maintainer.pl has different behavior for files that\n> +\t match F: pattern and matches of N: patterns. By default,\n> +\t get_maintainer will not look at git log history when an F: pattern\n> +\t match occurs. When an N: match occurs, git log history is used\n> +\t to also notify the people that have git commit signatures.\n> +\tK: *Content regex* (perl extended) pattern match in a patch or file.\n> +\t For instance:\n> +\t K: of_get_profile\n> +\t matches patches or files that contain \"of_get_profile\"\n> +\t K: \\b(printk|pr_(info|err))\\b\n> +\t matches patches or files that contain one or more of the words\n> +\t printk, pr_info or pr_err\n> +\t One regex pattern per line. Multiple K: lines acceptable.\n> +\n> +Maintainers List\n> +----------------\n> +\n> +.. note:: When reading this list, please look for the most precise areas\n> + first. When adding to this list, please keep the entries in\n> + alphabetical order.\n> +\n> +3C59X NETWORK DRIVER\n> +M:\tSteffen Klassert \n> +L:\tnetdev@vger.kernel.org\n> +S:\tOdd Fixes\n> +F:\tDocumentation/networking/device_drivers/ethernet/3com/vortex.rst\n> +F:\tdrivers/net/ethernet/3com/3c59x.c\n> +\n> +...\n> +\n> +THE REST\n> +M:\tLinus Torvalds \n> +L:\tlinux-kernel@vger.kernel.org\n> +S:\tBuried alive in reporters\n> +T:\tgit git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git\n> +F:\t*\n> +F:\t*/\n>\n> base-commit: 11c821f2f2a31e70fb5cc449f9a29401c333aad2\n"},{"id":"491389","messageId":"xmqq8r27nhwo.fsf@gitster.g","threadId":"61185","inReplyTo":"xmqqsf0gvjrg.fsf@gitster.g","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-03-25T02:51:03Z","receivedAt":"2024-03-25T02:51:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> I am more worried about how the file is used and maintained. Some\n> things to think about while in the \"spurred discussion\" I can think\n> of are:\n> ...\n> - Is the project big enough to require this (especially for the\n> purpose of (1)), or would\n>\n> $ git shortlog -n --no-merges --since=24.months -- path-to-file\n>\n> be sufficient and more importantly the value that it will keep\n> current automatically outweigh the benefit of having this file\n> that can go stale? To answer this question, we'd need to know\n> the turnover rates of past project contributors, of course. If\n> it is too high, having such a list may help for (1) and (3)\n> above.\n>\n> - How binding is it for a contributor to be on this list as an area\n> expert? Will there be concrete \"expected response time\"? It can\n> be different for each area expert, of course. I'd expect better\n> from those who work on Git as a major part of their job and\n> contributes some part of their work product back to the upstream,\n> than from folks who do Git as a hobby. Is each contributer\n> expected to volunteer to be on this list, with self declared\n> service level target?\n>\n> - With many good reviewer candidates being employed in companies\n> and doing Git as part of their job, how would we handle folks\n> getting transferred out of the Git ecosystem? Unlike in a\n> corporate environment, nominating successors who have no track\n> record in the community by the current area expert would not work\n> at all. The successors themselves have to earn respect by\n> demonstrating their own competence, which would take time.\n>\n> There may be many others.\n\nSo here are some more from the top of my head.\n\n - Corollary to \"nominating successors from the group at your\n company may not work well\", it may be hard to self-nominate\n yourself as an area expert if you are not confident that others\n consider you to be one.\n\n - How authoritative should these \"maintainers\" be? Do they have\n the final say to even override a concensus in a discussion if\n needed, when clueless discussion participants are drawing a\n conclusion that would hurt the codebase in the longer term?\n\n - For whom do we partition the areas? \"For revision walking using\n connectivity bitmaps, experts are ...\" sounds (at least to me)\n like a plausible and reasonable way to define an expertise area,\n but the description of the area may be understood only by those\n who are reasonably familiar with the way how \"git log\" internally\n works, for example. Is it OK to assume that the reader has some\n basic understanding of how the system works in order to use the\n maintainer list effectively?\n\n - The above worry may be reduced if we partition the area primarily\n along the file boundaries. If a set of functions that are not\n logically related to feature X but has to be in the same\n compilation unit for some reason live in the file whose primary\n purpose is to house implementation of the feature X, it may give\n us an interesting project to figure out how to separate them out\n and give them \"correct\" place, and the end result, even though it\n is a side effect, would be a more modular and readable code.\n\n - If we adopt the file format from the kernel project, can we\n leverage their tooling as well to query the maintainers file? I\n thought they have a tool that reads your patch into and figures\n out what area is being touched to spit out a good set of Cc\n candidates?\n\n - Can contrib/contacts/git-contacts be taught about this new source\n of information, and if so how?\n\n - Once we start breaking down the system into expertise areas, are\n there areas without any existng experts already? If you send\n patches to the list right now in the following areas, I do not\n think you'll find capable reviewers whose acks weigh well enough\n [*]: gitk, git-gui, contrib/completion, git-p4, gitweb, git-svn.\n\n * Please raise a hand and say \"No, you know I am very familiar\n with that area; you just simply forgot about me because we\n have not seen any patches in the area recently\".\n\n - When there are no active area experts, what would the default\n action be? We would risk degrading the quality of such\n \"neglected\" part of the system if we adopt \"anything gets\n accepted blindly\" approach, so I would really want to avoid it.\n\n - When an area with incumbent experts sees interest from some\n developers, it is the best for these new people to demonstrate\n their own competence and earn community's trust to eventually\n become the area experts themselves, but that may not be so easy\n in practice due to chicken-and-egg problem.\n"},{"id":"491618","messageId":"owlybk701vjz.fsf@fine.c.googlers.com","threadId":"61185","inReplyTo":"xmqqsf0gvjrg.fsf@gitster.g","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2024-03-26T22:24:00Z","receivedAt":"2024-03-26T22:24:02Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Junio C Hamano writes:\n\n> \"Linus Arver via GitGitGadget\" writes:\n>\n>> From: Linus Arver \n>>\n>> This patch is designed to spur discussion about adding an official\n>> MAINTAINERS file to our project. The hope is that it could be used as a\n>> reference in (at least) the following scenarios:\n>>\n>> (1) [CC list] patch authors want to know who to CC on their\n>> submissions, without resorting to git-blame-level of precision;\n>>\n>> (2) [escalation path] patch authors have been waiting 1+ weeks for\n>> review comments, but are not sure who to escalate to (other than\n>> Junio);\n>>\n>> (3) [status tracking] record former maintainers/reviewers who are now\n>> inactive.\n>>\n>> In addition having a MAINTAINERS file could give a more official sense\n>> of ownership in the codebase.\n>\n> OK. They are understandable goals.\n>\n> As to the format of the actual file, I do not have much opinion.\n> What works for the kernel may or may not work for us, as the project\n> size is very different, but I am fairly confident that we can agree\n> on something usable.\n>\n> I am more worried about how the file is used and maintained. Some\n> things to think about while in the \"spurred discussion\" I can think\n> of are:\n>\n> - Is the project big enough to require this (especially for the\n> purpose of (1)), or would\n>\n> $ git shortlog -n --no-merges --since=24.months -- path-to-file\n>\n> be sufficient and more importantly the value that it will keep\n> current automatically outweigh the benefit of having this file\n> that can go stale? To answer this question, we'd need to know\n> the turnover rates of past project contributors, of course. If\n> it is too high, having such a list may help for (1) and (3)\n> above.\n>\n> - How binding is it for a contributor to be on this list as an area\n> expert? Will there be concrete \"expected response time\"? It can\n> be different for each area expert, of course. I'd expect better\n> from those who work on Git as a major part of their job and\n> contributes some part of their work product back to the upstream,\n> than from folks who do Git as a hobby. Is each contributer\n> expected to volunteer to be on this list, with self declared\n> service level target?\n>\n> - With many good reviewer candidates being employed in companies\n> and doing Git as part of their job, how would we handle folks\n> getting transferred out of the Git ecosystem? Unlike in a\n> corporate environment, nominating successors who have no track\n> record in the community by the current area expert would not work\n> at all. The successors themselves have to earn respect by\n> demonstrating their own competence, which would take time.\n>\n> There may be many others.\n\nThanks for the initial comments! I will try to formulate a response\nsoon while I consider your other comments also.\n"},{"id":"491621","messageId":"ZgNcvR8STOUxxc1e@nand.local","threadId":"61185","inReplyTo":"xmqqsf0gvjrg.fsf@gitster.g","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-03-26T23:39:41Z","receivedAt":"2024-03-26T23:39:49Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Sat, Mar 23, 2024 at 12:19:15PM -0700, Junio C Hamano wrote:\n> - Is the project big enough to require this (especially for the\n> purpose of (1)), or would\n>\n> $ git shortlog -n --no-merges --since=24.months -- path-to-file\n>\n> be sufficient and more importantly the value that it will keep\n> current automatically outweigh the benefit of having this file\n> that can go stale? To answer this question, we'd need to know\n> the turnover rates of past project contributors, of course. If\n> it is too high, having such a list may help for (1) and (3)\n> above.\n\nI might be biased, but I think that we are not quite there, yet.\nSubjectively, I find myself working in areas where I mostly know who to\nCC based on what parts of the tree that I'm touching. But in the cases\nwhere I do not, the shortlog --since=2.years.ago is usually pretty\nsmall.\n\nThe output below lists number of individuals in the right-hand column,\nand the number of files with that many individuals having touched it in\nthe last two years in the left-hand column:\n\n for f in $(git ls-files **/*.{c,h})\n do\n git shortlog -s --since-as-filter=2.years.ago -- $f | wc -l \\\n || return 1\n done |\n sort -n | uniq -c | sort -rnk1\n 192 1\n 160 0\n 112 2\n 94 3\n 80 4\n 68 5\n 40 6\n 30 9\n 27 8\n 25 7\n 19 11\n 12 10\n 11 12\n 5 17\n 5 14\n 3 13\n 2 18\n 2 16\n 1 22\n 1 20\n 1 19\n 1 15\n\nSo a vast majority of *.ch files have fewer than 10 individuals working\non it in the past two years. By my count, there are 891 total source\nfiles matching **/*.{c,h}, 828 of which have fewer than 10 people\nworking on it.\n\nIOW, ~92.3% of the project is touched by no more than 9 people in the\nlast two years.\n\nThat kind of scale doesn't strike me as something that needs something\nlike a MAINTAINERS file to help make sense of it. It's possible that\nsome of the files that see more contributors might need some sort of\naide, but there are so few of them I have a hard time imagining it.\n\n> - How binding is it for a contributor to be on this list as an area\n> expert? Will there be concrete \"expected response time\"? It can\n> be different for each area expert, of course. I'd expect better\n> from those who work on Git as a major part of their job and\n> contributes some part of their work product back to the upstream,\n> than from folks who do Git as a hobby. Is each contributer\n> expected to volunteer to be on this list, with self declared\n> service level target?\n\nI share your concern here, too.\n\nAnother thought that comes to mind is the difference between\n\"maintainer\" and \"reviewer\". For a file with, say, 4 committers in the\npast two years, I imagine that as the maintainer that you'd give about\nequal weight to any of their reviews (with obvious exceptions, like if\nsomeone had showed up in the shortlog over a much longer period, or had\nsignificantly more or substantial patches in a given area).\n\nThose kinds of things are hard to quantify exactly, and perhaps that is\nthe point of a MAINTAINERS file. But I think quantifying those things\nmatters a lot more when you have dozens or more individuals contributing\nto files across the tree, and the numbers above show that (at least for\na large majority of the project) we're simply not there yet.\n\nThanks,\nTaylor\n"},{"id":"491622","messageId":"xmqqwmpo5yk4.fsf@gitster.g","threadId":"61185","inReplyTo":"ZgNcvR8STOUxxc1e@nand.local","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-03-27T00:05:31Z","receivedAt":"2024-03-27T00:05:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Taylor Blau writes:\n\n>> - How binding is it for a contributor to be on this list as an area\n>> expert? Will there be concrete \"expected response time\"? It can\n>> be different for each area expert, of course. I'd expect better\n>> from those who work on Git as a major part of their job and\n>> contributes some part of their work product back to the upstream,\n>> than from folks who do Git as a hobby. Is each contributer\n>> expected to volunteer to be on this list, with self declared\n>> service level target?\n>\n> I share your concern here, too.\n\nBut I wasn't expressing any concern above ;-)\n\nI'd consider it a progress if we can give contributors (and the\nmaintainer, too) more predictable review experience. If we can even\noptionally give some assurance on the response time, e.g., \"I'll to\nrespond to and usher to completion any patches in this area if they\nare promising within X days; I may not respond to all patches and\ncertainly not to ones that I do not find interesting\" would already\nbe better than some patches that do not see any reviews for three\nweeks without such an \"optional\" maintainer.\n\n> Those kinds of things are hard to quantify exactly, and perhaps that is\n> the point of a MAINTAINERS file.\n\nYeah, I am not interested in what exact form such a list of folks\nwho are willing to help guiding topics along comes from. What I am\nhoping to find out is if we can come up with a bit more structured\nway to say \"yes\" or \"no\" to topics, rather than the current \"nobody\nmay be interested in a topic, in which case it is anybody's guess\nwhat will happen to it\" (actually the default is \"to drop\", and I\noften end up to be \"somebody who gets sympathetic and reads the\ntopic to salvage, instead of the default action that is to drop\").\n\nThanks.\n"},{"id":"491627","messageId":"owly7cho1eh4.fsf@fine.c.googlers.com","threadId":"61185","inReplyTo":"xmqqsf0gvjrg.fsf@gitster.g","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2024-03-27T04:32:55Z","receivedAt":"2024-03-27T04:32:57Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Junio C Hamano writes:\n\n> \"Linus Arver via GitGitGadget\" writes:\n>\n>> From: Linus Arver \n>>\n>> This patch is designed to spur discussion about adding an official\n>> MAINTAINERS file to our project. The hope is that it could be used as a\n>> reference in (at least) the following scenarios:\n>>\n>> (1) [CC list] patch authors want to know who to CC on their\n>> submissions, without resorting to git-blame-level of precision;\n>>\n>> (2) [escalation path] patch authors have been waiting 1+ weeks for\n>> review comments, but are not sure who to escalate to (other than\n>> Junio);\n>>\n>> (3) [status tracking] record former maintainers/reviewers who are now\n>> inactive.\n>>\n>> In addition having a MAINTAINERS file could give a more official sense\n>> of ownership in the codebase.\n>\n> OK. They are understandable goals.\n>\n> As to the format of the actual file, I do not have much opinion.\n> What works for the kernel may or may not work for us, as the project\n> size is very different, but I am fairly confident that we can agree\n> on something usable.\n\nAgreed.\n\n> I am more worried about how the file is used and maintained. Some\n> things to think about while in the \"spurred discussion\" I can think\n> of are:\n>\n> - Is the project big enough to require this (especially for the\n> purpose of (1)), or would\n>\n> $ git shortlog -n --no-merges --since=24.months -- path-to-file\n>\n> be sufficient and more importantly the value that it will keep\n> current automatically outweigh the benefit of having this file\n> that can go stale?\n>\n> To answer this question, we'd need to know\n> the turnover rates of past project contributors, of course. If\n> it is too high, having such a list may help for (1) and (3)\n> above.\n\nIn addition to checking git-shortlog on the Git repo, perhaps it's also\nworth running a similar query against the public-inbox repo of this\nlist? We could perhaps use a script to generate this list automatically\nevery Git release (or some other cadence that we undergo regularly)?\n\n> - How binding is it for a contributor to be on this list as an area\n> expert? Will there be concrete \"expected response time\"? It can\n> be different for each area expert, of course. I'd expect better\n> from those who work on Git as a major part of their job and\n> contributes some part of their work product back to the upstream,\n> than from folks who do Git as a hobby. Is each contributer\n> expected to volunteer to be on this list, with self declared\n> service level target?\n\nIdeally there should be some teeth to the document/agreement (esp for\nservice level targets), but I think practically the best we can do is\npositive reinforcement. So maybe a prominent \"The Git Code Review Team\"\nweb page (somewhere on git-scm.com?) with profile photos and short\nbiographies should be enough to motivate people to stay engaged and keep\ntheir spot.\n\nI realize that such an idea is beyond the scope of a simple MAINTAINERS\n(or similar) file that's checked into the Git code repo, but I think\nit's worth stating as a thought experiment. The overall point I want to\nmake is that we need to be extra-thankful to those who sign up to say\n\"yes, I can review patches in areas X, Y, Z\" and recognize (in a very\nofficial way) their generosity in contributing back to this project.\n\n> - With many good reviewer candidates being employed in companies\n> and doing Git as part of their job, how would we handle folks\n> getting transferred out of the Git ecosystem? Unlike in a\n> corporate environment, nominating successors who have no track\n> record in the community by the current area expert would not work\n> at all. The successors themselves have to earn respect by\n> demonstrating their own competence, which would take time.\n\nUnfortunately I don't think there's a good answer here. I agree that\nonly those who have demonstrated a good track record should become a\n\"successor\".\n\nOTOH, if we are fortunate enough to have multiple people sign up for a\nparticular area, then maybe that can be a sub-team and finding a\nsuccessor won't be such a big deal. It would only be a problem for those\nareas where there is only 1 person who signed up for it.\n"},{"id":"491628","messageId":"owly34sc1bo1.fsf@fine.c.googlers.com","threadId":"61185","inReplyTo":"xmqq8r27nhwo.fsf@gitster.g","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2024-03-27T05:33:34Z","receivedAt":"2024-03-27T05:33:36Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Oops, I should have just responded to this email once as you quoted\nyour original reply. Sorry for the inconvenience.\n\nBTW thanks for spurring on the discussion. I've also CC'ed additional\nfolks directly to try to get more feedback for this topic.\n\n\nJunio C Hamano writes:\n\n> Junio C Hamano writes:\n>\n> [...]\n>\n> So here are some more from the top of my head.\n>\n> - Corollary to \"nominating successors from the group at your\n> company may not work well\", it may be hard to self-nominate\n> yourself as an area expert if you are not confident that others\n> consider you to be one.\n\nThere probably needs to be some sort of voting mechanism to affirm\nmembership into the \"maintainers\" group.\n\n> - How authoritative should these \"maintainers\" be? Do they have\n> the final say to even override a concensus in a discussion if\n> needed, when clueless discussion participants are drawing a\n> conclusion that would hurt the codebase in the longer term?\n\nI want to say \"it depends\", but for sake of simplicity, I think \"yes\" is\na better answer than \"no\". If the existing area expert is not happy with\nthe direction of a patch series... tough luck, try again. If we end up\noverruling the opinions of established experts very often then the title\nof \"maintainer\" loses teeth and I don't like that consequence.\n\nIIUC in the Linux Kernel people pull large chunks of changes from each\nother until it all converges into the one owned by Torvalds. That model\nworks because of the \"network of trust\" amongst the various maintainers,\neach maintainer being an area expert.\n\nI'm digressing a little bit here, but perhaps the \"area expert\" model\nwill only work if we move to a more Kernel-like model with multiple\nseparate \"collection points\" of patches (where there are multiple\nmaintainers). But I don't think Git is large enough where that model\nmakes sense. I'm not sure.\n\n> - For whom do we partition the areas? \"For revision walking using\n> connectivity bitmaps, experts are ...\" sounds (at least to me)\n> like a plausible and reasonable way to define an expertise area,\n> but the description of the area may be understood only by those\n> who are reasonably familiar with the way how \"git log\" internally\n> works, for example. Is it OK to assume that the reader has some\n> basic understanding of how the system works in order to use the\n> maintainer list effectively?\n\nI think that assumption is fine. We have to start somewhere.\n\nBTW I expect such a \"maintainers\" doc to evolve a bit as we hit bumps on\nthe road along the way.\n\n> - The above worry may be reduced if we partition the area primarily\n> along the file boundaries. If a set of functions that are not\n> logically related to feature X but has to be in the same\n> compilation unit for some reason live in the file whose primary\n> purpose is to house implementation of the feature X, it may give\n> us an interesting project to figure out how to separate them out\n> and give them \"correct\" place, and the end result, even though it\n> is a side effect, would be a more modular and readable code.\n\nYup, file boundaries may be the simplest one.\n\nAnother partitioning dimension might be individual internal libraries\n(header files to start, although some things like git-compat-util.h\nmight need more than one expert due to its complexity).\n\n> - If we adopt the file format from the kernel project, can we\n> leverage their tooling as well to query the maintainers file? I\n> thought they have a tool that reads your patch into and figures\n> out what area is being touched to spit out a good set of Cc\n> candidates?\n\nYes. I found guidance [1] which suggests using scripts/get_maintainer.pl\n[2] to find the CC list. And this script appears [3] to use the\nMAINTAINERS file format to do its work.\n\nI'm not a big fan of Perl but I suppose as long as we keep the same\nformat we can always just reuse that script (assuming it doesn't have\nKernel-only things hardcoded into it that make it unusable outside the\nKernel).\n\n> - Can contrib/contacts/git-contacts be taught about this new source\n> of information, and if so how?\n\nWow, I had no idea this existed.\n\nOne (stupid) idea would be to do a set union operation with the output\nof git-contacts with the output of scripts/get_maintainer.pl.\n\n> - Once we start breaking down the system into expertise areas, are\n> there areas without any existng experts already? If you send\n> patches to the list right now in the following areas, I do not\n> think you'll find capable reviewers whose acks weigh well enough\n> [*]: gitk, git-gui, contrib/completion, git-p4, gitweb, git-svn.\n>\n> * Please raise a hand and say \"No, you know I am very familiar\n> with that area; you just simply forgot about me because we\n> have not seen any patches in the area recently\".\n\nI think the lack of experts in certain areas is fine. It may even be\nthee case that there are only a few experts (in a few areas) around to\nstart with.\n\n> - When there are no active area experts, what would the default\n> action be? We would risk degrading the quality of such\n> \"neglected\" part of the system if we adopt \"anything gets\n> accepted blindly\" approach, so I would really want to avoid it.\n\nPerhaps we could have a team of \"code reviewers\" who can be available to\nreview patches at some basic level, not at the level of experts? Over\ntime such reviewers could graduate to become an area expert they like to\nwork on. The idea is to make sure that there's always a steady pipeline\nof would-be-experts who are ready to join the \"maintainers\" ranks, when\nthe existing maintainers inevitably become inactive or move on from the\nproject.\n\nAnyway, to answer your immediate question, I think the default action\nwould still be to wait for code reviews from known people (who are not\nnew to the community).\n\n> - When an area with incumbent experts sees interest from some\n> developers, it is the best for these new people to demonstrate\n> their own competence and earn community's trust to eventually\n> become the area experts themselves, but that may not be so easy\n> in practice due to chicken-and-egg problem.\n\nYeah I agree. I guess I anticipated this problem with my response just\nabove WRT having a pipeline of would-be-experts. To restate, I think\nit's important to have a healthy number of people across all levels of\nexpertise (beginner, intermediate, advanced) in the community. Maybe we\nhave that already? If so, the trick would be to incentivize the\nbeginners and intermediate level folks to stick around long enough to\nbecome experts.\n\nThe GSoC [4] program is one way, although I don't know how successful it\nhas been (and I don't think it's very scalable).\n\n\n[1] https://www.kernel.org/doc/html/latest/process/submitting-patches.html#select-the-recipients-for-your-patch\n[2] https://github.com/torvalds/linux/blob/master/scripts/get_maintainer.pl\n[3] https://github.com/torvalds/linux/blob/7033999ecd7b8cf9ea59265035a0150961e023ee/scripts/get_maintainer.pl#L345\n[4] https://summerofcode.withgoogle.com/\n"},{"id":"491644","messageId":"ZgPIEgFGVokYWc-H@tanuki","threadId":"61185","inReplyTo":"xmqq8r27nhwo.fsf@gitster.g","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-03-27T07:17:38Z","receivedAt":"2024-03-27T07:17:43Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Sun, Mar 24, 2024 at 07:51:03PM -0700, Junio C Hamano wrote:\n> Junio C Hamano writes:\n> \n> > I am more worried about how the file is used and maintained. Some\n> > things to think about while in the \"spurred discussion\" I can think\n> > of are:\n> > ...\n> > - Is the project big enough to require this (especially for the\n> > purpose of (1)), or would\n> >\n> > $ git shortlog -n --no-merges --since=24.months -- path-to-file\n> >\n> > be sufficient and more importantly the value that it will keep\n> > current automatically outweigh the benefit of having this file\n> > that can go stale? To answer this question, we'd need to know\n> > the turnover rates of past project contributors, of course. If\n> > it is too high, having such a list may help for (1) and (3)\n> > above.\n\nI don't think of this as \"big enough to require this\". I rather think\nabout the onboarding experience for new folks here. Sure, we can ask\nthem to \"Please run git-shortlog(1) to figure out whom to Cc\". But if we\ninstead provide a nice script that does it for them then we make their\nlifes easier.\n\nIt's also easy to include this for example into GitGitGadget in an\nautomated way.\n\n> > - How binding is it for a contributor to be on this list as an area\n> > expert? Will there be concrete \"expected response time\"? It can\n> > be different for each area expert, of course. I'd expect better\n> > from those who work on Git as a major part of their job and\n> > contributes some part of their work product back to the upstream,\n> > than from folks who do Git as a hobby. Is each contributer\n> > expected to volunteer to be on this list, with self declared\n> > service level target?\n\nThis is a good question. I don't really think that we should enforce any\nkind of \"service level agreements\" here. I think people who are deeply\ninvested into any of the subsystems are mostly doing a good job of\nreplying to related patch series already, so I don't see an urgent need\nto enforce something here. I would rather assume that we have problems\nin areas which _don't_ have an active expert, and I doubt that the\nintroduction of a \"MAINTAINERS\" file would help here.\n\nI would thus reformulate the proposal from \"MAINTAINERS\" to \"REVIEWERS\".\nInstead of saying that person A is a maintainer of subsystem B, it would\nsay person A has a keen interest in subsystem B and would thus be a very\ngood candidate to Cc in all your mails touching this subsystem.\n\n> > - With many good reviewer candidates being employed in companies\n> > and doing Git as part of their job, how would we handle folks\n> > getting transferred out of the Git ecosystem? Unlike in a\n> > corporate environment, nominating successors who have no track\n> > record in the community by the current area expert would not work\n> > at all. The successors themselves have to earn respect by\n> > demonstrating their own competence, which would take time.\n\nI think that this problem would go away if we reformulated the problem\nto be about discoverability of interested folks instead of setting up\nsubmaintainers.\n\n> So here are some more from the top of my head.\n> \n> - Corollary to \"nominating successors from the group at your\n> company may not work well\", it may be hard to self-nominate\n> yourself as an area expert if you are not confident that others\n> consider you to be one.\n\nI also think that this becomes less of a problem because you don't have\nto be _the_ expert in order to say \"I'm curious, please Cc me here\".\n\n> - How authoritative should these \"maintainers\" be? Do they have\n> the final say to even override a concensus in a discussion if\n> needed, when clueless discussion participants are drawing a\n> conclusion that would hurt the codebase in the longer term?\n\nDo we actually need this? I'm not too thrilled about people having more\nauthority simply because they are around longer and have been appointed\nas a maintainer. I think that discussions should be decided based on the\nmerit of arguments, not based on the role one of the participants has.\n\nThis is also based on the assumption that experts of a subsystem would\nbe able to highlight why exactly something is a bad idea and argue\naccordingly. Thus, in the ideal case, no authority should be needed\nexcept for the authority that their inherent knowledge already brings\nwith them.\n\n> - For whom do we partition the areas? \"For revision walking using\n> connectivity bitmaps, experts are ...\" sounds (at least to me)\n> like a plausible and reasonable way to define an expertise area,\n> but the description of the area may be understood only by those\n> who are reasonably familiar with the way how \"git log\" internally\n> works, for example. Is it OK to assume that the reader has some\n> basic understanding of how the system works in order to use the\n> maintainer list effectively?\n> \n> - The above worry may be reduced if we partition the area primarily\n> along the file boundaries. If a set of functions that are not\n> logically related to feature X but has to be in the same\n> compilation unit for some reason live in the file whose primary\n> purpose is to house implementation of the feature X, it may give\n> us an interesting project to figure out how to separate them out\n> and give them \"correct\" place, and the end result, even though it\n> is a side effect, would be a more modular and readable code.\n\nI think partitioning intersted folks along file boundaries would be the\neasiest. Also because...\n\n> - If we adopt the file format from the kernel project, can we\n> leverage their tooling as well to query the maintainers file? I\n> thought they have a tool that reads your patch into and figures\n> out what area is being touched to spit out a good set of Cc\n> candidates?\n\n... the tooling from the kernel project already works in this way. They\ndo have \"scripts/get_maintainer.pl\" that can be invoked with a set of\nfiles that have changed, and it will then spit out a list of folks to Cc\nas declared in the MAINTAINERS file.\n\nPatrick\n"},{"id":"491694","messageId":"xmqq4jcr6bx2.fsf@gitster.g","threadId":"61185","inReplyTo":"owly7cho1eh4.fsf@fine.c.googlers.com","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-03-27T13:29:13Z","receivedAt":"2024-03-27T13:29:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Linus Arver writes:\n\n> I realize that such an idea is beyond the scope of a simple MAINTAINERS\n> (or similar) file that's checked into the Git code repo, but I think\n> it's worth stating as a thought experiment.\n\nAs we already have agreed that neither of us care the exact format\nof the file (yet), regardless of how a contributor, who is about to\nsend a patch, will find an area \"maintainer\" to help the patch along\nthe process, it is far more important to discuss and decide what\nresponsibilities and authorities are expected of these maintainers.\n\nThe development community has been fairly loosely organized so far,\nbut I'd like to see responsibility and authority spread a bit more\nwidely yet still not too thinly to compromise the project integrity.\n\n> The overall point I want to make is that we need to be\n> extra-thankful to those who sign up to say \"yes, I can review\n> patches in areas X, Y, Z\" and recognize (in a very official way)\n> their generosity in contributing back to this project.\n\nYup.\n\n"},{"id":"491895","messageId":"owlyttkn61nq.fsf@fine.c.googlers.com","threadId":"61185","inReplyTo":"xmqq4jcr6bx2.fsf@gitster.g","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2024-03-30T17:59:53Z","receivedAt":"2024-03-30T17:59:55Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Junio C Hamano writes:\n\n> Linus Arver writes:\n>\n>> I realize that such an idea is beyond the scope of a simple MAINTAINERS\n>> (or similar) file that's checked into the Git code repo, but I think\n>> it's worth stating as a thought experiment.\n>\n> As we already have agreed that neither of us care the exact format\n> of the file (yet), regardless of how a contributor, who is about to\n> send a patch, will find an area \"maintainer\" to help the patch along\n> the process, it is far more important to discuss and decide what\n> responsibilities and authorities are expected of these maintainers.\n\nI'm starting to think that the new responsibility should be as small as\npossible, and build from there. So the smallest bit of (initial?)\nresponsibility expected of the new roster of maintainers could be\n\"maintainer must respond to CC pings on the list within 7 days\".\n\nFor those who have more time to spend on the project, the next rung of\nresponsibility could be \"maintainer is available to review patches\noutside of their domain of expertise if no one else has reviewed the\nseries in 7 days\".\n\nI haven't thought too much about the \"authority\" part yet.\n\n> The development community has been fairly loosely organized so far,\n> but I'd like to see responsibility and authority spread a bit more\n> widely yet still not too thinly to compromise the project integrity.\n\nAgreed.\n"},{"id":"491896","messageId":"owlyr0fr61hy.fsf@fine.c.googlers.com","threadId":"61185","inReplyTo":"ZgPIEgFGVokYWc-H@tanuki","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2024-03-30T18:03:21Z","receivedAt":"2024-03-30T18:03:23Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Patrick Steinhardt writes:\n\n> On Sun, Mar 24, 2024 at 07:51:03PM -0700, Junio C Hamano wrote:\n>> Junio C Hamano writes:\n> [...]\n>\n> I would thus reformulate the proposal from \"MAINTAINERS\" to \"REVIEWERS\".\n> Instead of saying that person A is a maintainer of subsystem B, it would\n> say person A has a keen interest in subsystem B and would thus be a very\n> good candidate to Cc in all your mails touching this subsystem.\n\nGood idea!\n"},{"id":"491901","messageId":"xmqq5xx3l7j0.fsf@gitster.g","threadId":"61185","inReplyTo":"owlyr0fr61hy.fsf@fine.c.googlers.com","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-03-30T21:44:03Z","receivedAt":"2024-03-30T21:44:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Linus Arver writes:\n\n> Patrick Steinhardt writes:\n>\n>> On Sun, Mar 24, 2024 at 07:51:03PM -0700, Junio C Hamano wrote:\n>>> Junio C Hamano writes:\n>> [...]\n>>\n>> I would thus reformulate the proposal from \"MAINTAINERS\" to \"REVIEWERS\".\n>> Instead of saying that person A is a maintainer of subsystem B, it would\n>> say person A has a keen interest in subsystem B and would thus be a very\n>> good candidate to Cc in all your mails touching this subsystem.\n>\n> Good idea!\n\nSeconded.\n"},{"id":"491993","messageId":"ZgsoOnle3CC8DqUR@nand.local","threadId":"61185","inReplyTo":"ZgPIEgFGVokYWc-H@tanuki","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-04-01T21:33:46Z","receivedAt":"2024-04-01T21:33:48Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Wed, Mar 27, 2024 at 08:17:38AM +0100, Patrick Steinhardt wrote:\n> On Sun, Mar 24, 2024 at 07:51:03PM -0700, Junio C Hamano wrote:\n> > Junio C Hamano writes:\n> >\n> > > I am more worried about how the file is used and maintained. Some\n> > > things to think about while in the \"spurred discussion\" I can think\n> > > of are:\n> > > ...\n> > > - Is the project big enough to require this (especially for the\n> > > purpose of (1)), or would\n> > >\n> > > $ git shortlog -n --no-merges --since=24.months -- path-to-file\n> > >\n> > > be sufficient and more importantly the value that it will keep\n> > > current automatically outweigh the benefit of having this file\n> > > that can go stale? To answer this question, we'd need to know\n> > > the turnover rates of past project contributors, of course. If\n> > > it is too high, having such a list may help for (1) and (3)\n> > > above.\n>\n> I don't think of this as \"big enough to require this\". I rather think\n> about the onboarding experience for new folks here. Sure, we can ask\n> them to \"Please run git-shortlog(1) to figure out whom to Cc\". But if we\n> instead provide a nice script that does it for them then we make their\n> lifes easier.\n\nDo you think that the script in contrib/contacts does a sufficient job\nat this?\n\nI admit that I am not a frequent user of it (mostly because I end up\neither having a good sense of who I want to review patches ahead of\ntime, and/or I end up just running 'shortlog'), so I can't vouch for its\naccuracy.\n\nBut from running it on a handful of patches just now locally while\nreplying to your email, it seems to do a reasonable job at identifying a\ngood set of candidate reviewers.\n\nPerhaps we haven't been as good at advertising this script as we could\nbe, and that's why it isn't as widely used as it could be? I'm not sure.\n\nThanks,\nTaylor\n"},{"id":"491998","messageId":"xmqqzfuc7muw.fsf@gitster.g","threadId":"61185","inReplyTo":"ZgsoOnle3CC8DqUR@nand.local","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-04-01T22:13:27Z","receivedAt":"2024-04-01T22:13:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Taylor Blau writes:\n\n>> I don't think of this as \"big enough to require this\". I rather think\n>> about the onboarding experience for new folks here. Sure, we can ask\n>> them to \"Please run git-shortlog(1) to figure out whom to Cc\". But if we\n>> instead provide a nice script that does it for them then we make their\n>> lifes easier.\n>\n> Do you think that the script in contrib/contacts does a sufficient job\n> at this?\n\nYup, that was my first reaction. If it is not sufficient to\nmechanically mine history with shortlog or blame or contacts, and if\nwe can add a high quality hand-curated input to improve the result\ncontacts gives us, that would be a progress. I view the MAINTAINERS\nformat just one way to give such human generated input.\n\n> Perhaps we haven't been as good at advertising this script as we could\n> be, and that's why it isn't as widely used as it could be? I'm not sure.\n\nGood point. Do we even mention it in MyFirstSomething docs?\n\n"},{"id":"492011","messageId":"owlymsqc62av.fsf@fine.c.googlers.com","threadId":"61185","inReplyTo":"xmqqzfuc7muw.fsf@gitster.g","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2024-04-02T00:22:48Z","receivedAt":"2024-04-02T00:22:50Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Junio C Hamano writes:\n\n> Taylor Blau writes:\n>\n> [...]\n>> Perhaps we haven't been as good at advertising this script as we could\n>> be, and that's why it isn't as widely used as it could be? I'm not sure.\n>\n> Good point. Do we even mention it in MyFirstSomething docs?\n\nI've pushed up a patch for review to mention it in our docs:\nhttps://lore.kernel.org/git/pull.1704.git.1712017205754.gitgitgadget@gmail.com\n\n(And, sorry for not simply pushing the patch to this thread because I\nonly know how to use GGG currently... Cheers)\n"},{"id":"492014","messageId":"ZguaLjWGte3zdQGW@tanuki","threadId":"61185","inReplyTo":"xmqqzfuc7muw.fsf@gitster.g","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-04-02T05:39:58Z","receivedAt":"2024-04-02T05:40:04Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Apr 01, 2024 at 03:13:27PM -0700, Junio C Hamano wrote:\n> Taylor Blau writes:\n> \n> >> I don't think of this as \"big enough to require this\". I rather think\n> >> about the onboarding experience for new folks here. Sure, we can ask\n> >> them to \"Please run git-shortlog(1) to figure out whom to Cc\". But if we\n> >> instead provide a nice script that does it for them then we make their\n> >> lifes easier.\n> >\n> > Do you think that the script in contrib/contacts does a sufficient job\n> > at this?\n\nI admittedly never used it much, either. I didn't see a lot of benefit\nbecause I can figure out myself whom to Cc. That would be less true for\nnewcomers to the community though, where it may be more useful.\n\n> Yup, that was my first reaction. If it is not sufficient to\n> mechanically mine history with shortlog or blame or contacts, and if\n> we can add a high quality hand-curated input to improve the result\n> contacts gives us, that would be a progress. I view the MAINTAINERS\n> format just one way to give such human generated input.\n\nAgreed. I don't think that we have to pick either MAINTAINERS or the\n\"contrib/contacts\" script, but would rather want the existing script to\nhonor MAINTAINERS as an additional data source.\n\nWhen it does know about both I also see myself using it more frequently\nin the future. It would be nice if git-send-email(1)/git-format-patch(1)\nhad a switch `--cc-command=` or similar that you can pass the script to\nso that To/Cc lines would be added automatically. The script then gets\nthe commit range as input and can decide based on whatever criteria whom\nto Cc. To the best of my knowledge that is not currently possible.\n\nPatrick\n"},{"id":"492015","messageId":"CAPig+cSp=GjQWF1t+O6w+Ad=NUmeAM8ZAQp+CeetERgiSaUe0g@mail.gmail.com","threadId":"61185","inReplyTo":"ZguaLjWGte3zdQGW@tanuki","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2024-04-02T05:46:22Z","receivedAt":"2024-04-02T05:46:34Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Tue, Apr 2, 2024 at 1:40 AM Patrick Steinhardt wrote:\n> When it does know about both I also see myself using it more frequently\n> in the future. It would be nice if git-send-email(1)/git-format-patch(1)\n> had a switch `--cc-command=` or similar that you can pass the script to\n> so that To/Cc lines would be added automatically. The script then gets\n> the commit range as input and can decide based on whatever criteria whom\n> to Cc. To the best of my knowledge that is not currently possible.\n\nI may be misunderstanding your statement, but this automated mode was\nexactly the original use-case. contrib/contacts/git-contacts.txt says\nthis:\n\n This command can be useful for determining the list of people with\n whom to discuss proposed changes, or for finding the list of\n recipients to Cc: when submitting a patch series via `git\n send-email`. For the latter case, `git contacts` can be used as\n the argument to `git send-email`'s `--cc-cmd` option.\n"},{"id":"492016","messageId":"Zgue0LGaAa5BfqKZ@tanuki","threadId":"61185","inReplyTo":"CAPig+cSp=GjQWF1t+O6w+Ad=NUmeAM8ZAQp+CeetERgiSaUe0g@mail.gmail.com","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-04-02T05:59:44Z","receivedAt":"2024-04-02T05:59:51Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, Apr 02, 2024 at 01:46:22AM -0400, Eric Sunshine wrote:\n> On Tue, Apr 2, 2024 at 1:40 AM Patrick Steinhardt wrote:\n> > When it does know about both I also see myself using it more frequently\n> > in the future. It would be nice if git-send-email(1)/git-format-patch(1)\n> > had a switch `--cc-command=` or similar that you can pass the script to\n> > so that To/Cc lines would be added automatically. The script then gets\n> > the commit range as input and can decide based on whatever criteria whom\n> > to Cc. To the best of my knowledge that is not currently possible.\n> \n> I may be misunderstanding your statement, but this automated mode was\n> exactly the original use-case. contrib/contacts/git-contacts.txt says\n> this:\n> \n> This command can be useful for determining the list of people with\n> whom to discuss proposed changes, or for finding the list of\n> recipients to Cc: when submitting a patch series via `git\n> send-email`. For the latter case, `git contacts` can be used as\n> the argument to `git send-email`'s `--cc-cmd` option.\n\nAh. I myself use git-format-patch(1) and mutt(1) to send the resulting\npatches, and that command doesn't know about `--cc-cmd`. But\ngit-send-email(1) in fact does, good to know. So my statement still\npartially stands, and we might want to make `--cc-cmd` available in\ngit-format-patch(1), too.\n\nPatrick\n"},{"id":"492018","messageId":"ZgukEQVqOgqAIIVR@tanuki","threadId":"61185","inReplyTo":"owlyttkn61nq.fsf@fine.c.googlers.com","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-04-02T06:22:09Z","receivedAt":"2024-04-02T06:22:15Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Sat, Mar 30, 2024 at 10:59:53AM -0700, Linus Arver wrote:\n> Junio C Hamano writes:\n> \n> > Linus Arver writes:\n> >\n> >> I realize that such an idea is beyond the scope of a simple MAINTAINERS\n> >> (or similar) file that's checked into the Git code repo, but I think\n> >> it's worth stating as a thought experiment.\n> >\n> > As we already have agreed that neither of us care the exact format\n> > of the file (yet), regardless of how a contributor, who is about to\n> > send a patch, will find an area \"maintainer\" to help the patch along\n> > the process, it is far more important to discuss and decide what\n> > responsibilities and authorities are expected of these maintainers.\n> \n> I'm starting to think that the new responsibility should be as small as\n> possible, and build from there. So the smallest bit of (initial?)\n> responsibility expected of the new roster of maintainers could be\n> \"maintainer must respond to CC pings on the list within 7 days\".\n> \n> For those who have more time to spend on the project, the next rung of\n> responsibility could be \"maintainer is available to review patches\n> outside of their domain of expertise if no one else has reviewed the\n> series in 7 days\".\n> \n> I haven't thought too much about the \"authority\" part yet.\n\nOne thing that makes me feel a bit uneasy about the authority part is\nthat contributors to Git are quite often direct competitors on the\ncompany level, as well. This never has been a problem in the past, quite\non the contrary: I really value the cross-competitor collaboration we\nhave in this project.\n\nBut I have to wonder what it can potentially lead to if we did assign\nmore authority to some contributors. Theoretically speaking, that would\nallow for sabotaging interests of a direct competitor.\n\nMind you, I don't think this would happen in the current state of the\nproject. I'm merely trying to think about worst-case scenarios, which\nmay or may not be helpful in this context.\n\nPatrick\n\n> > The development community has been fairly loosely organized so far,\n> > but I'd like to see responsibility and authority spread a bit more\n> > widely yet still not too thinly to compromise the project integrity.\n> \n> Agreed.\n"},{"id":"492026","messageId":"ZgutC_ddW_Psmlcl@tanuki","threadId":"61185","inReplyTo":"xmqq4jcr6bx2.fsf@gitster.g","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-04-02T07:00:27Z","receivedAt":"2024-04-02T07:00:32Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Wed, Mar 27, 2024 at 06:29:13AM -0700, Junio C Hamano wrote:\n> The development community has been fairly loosely organized so far,\n> but I'd like to see responsibility and authority spread a bit more\n> widely yet still not too thinly to compromise the project integrity.\n\nI guess the main motivation of this statement is to reduce your load in\nparticular, right? If so, do you have any particular pain points that\ncan be spread across the community that would help you? Or is it really\nonly spreading the review load by relying more on subsystem-maintainers?\n\nPatrick\n"},{"id":"492068","messageId":"xmqqzfub66oq.fsf@gitster.g","threadId":"61185","inReplyTo":"ZgutC_ddW_Psmlcl@tanuki","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-04-02T17:00:21Z","receivedAt":"2024-04-02T17:00:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Wed, Mar 27, 2024 at 06:29:13AM -0700, Junio C Hamano wrote:\n>> The development community has been fairly loosely organized so far,\n>> but I'd like to see responsibility and authority spread a bit more\n>> widely yet still not too thinly to compromise the project integrity.\n>\n> I guess the main motivation of this statement is to reduce your load in\n> particular, right? If so, do you have any particular pain points that\n> can be spread across the community that would help you? Or is it really\n> only spreading the review load by relying more on subsystem-maintainers?\n\nIt is not for load reduction, per-se.\n\nI wish people spent more time and effort on reviewing and helping\nothers to polish topics as much as writing their own topic. We see\ncorporate sponsored entities propose a feature, polish it with\nreviewers, and then after the topic lands and collect their perf\nscores, leave it bitrot, making it \"the community's problem\" to\nmaintain it. They may even have to leave the project due to reorg.\n\nSomebody comes with a patch in such an area, and receives no\nresponse. The only two ways I see to reduce such \"abandoned parts\"\nof the system are:\n\n * Those who are still with the project but their interest moved to\n other areas in the project to come back to help in the area they\n were involved in, and\n\n * Those who haven't been involved in an area to grow expertise in\n it.\n\nThe latter is far more sustainable than the former. People forget\nand become no longer more expert than others who have fresh interst\nin the same area. But for that to happen, we first need to know\nwhere the gaps of expertise coverage are. If we try to spread\nresponsibility and authority, we will quickly identify these areas\nas we find no experts in these areas.\n"},{"id":"492194","messageId":"owlyzfuarm1o.fsf@fine.c.googlers.com","threadId":"61185","inReplyTo":"ZgukEQVqOgqAIIVR@tanuki","subject":"Re: [PATCH] RFC: add MAINTAINERS file","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2024-04-04T00:47:31Z","receivedAt":"2024-04-04T00:47:33Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Patrick Steinhardt writes:\n\n> On Sat, Mar 30, 2024 at 10:59:53AM -0700, Linus Arver wrote:\n>> Junio C Hamano writes:\n>> \n>> > Linus Arver writes:\n>> >\n>> >> I realize that such an idea is beyond the scope of a simple MAINTAINERS\n>> >> (or similar) file that's checked into the Git code repo, but I think\n>> >> it's worth stating as a thought experiment.\n>> >\n>> > As we already have agreed that neither of us care the exact format\n>> > of the file (yet), regardless of how a contributor, who is about to\n>> > send a patch, will find an area \"maintainer\" to help the patch along\n>> > the process, it is far more important to discuss and decide what\n>> > responsibilities and authorities are expected of these maintainers.\n>> \n>> I'm starting to think that the new responsibility should be as small as\n>> possible, and build from there. So the smallest bit of (initial?)\n>> responsibility expected of the new roster of maintainers could be\n>> \"maintainer must respond to CC pings on the list within 7 days\".\n>> \n>> For those who have more time to spend on the project, the next rung of\n>> responsibility could be \"maintainer is available to review patches\n>> outside of their domain of expertise if no one else has reviewed the\n>> series in 7 days\".\n>> \n>> I haven't thought too much about the \"authority\" part yet.\n>\n> One thing that makes me feel a bit uneasy about the authority part is\n> that contributors to Git are quite often direct competitors on the\n> company level, as well. This never has been a problem in the past, quite\n> on the contrary: I really value the cross-competitor collaboration we\n> have in this project.\n>\n> But I have to wonder what it can potentially lead to if we did assign\n> more authority to some contributors. Theoretically speaking, that would\n> allow for sabotaging interests of a direct competitor.\n>\n> Mind you, I don't think this would happen in the current state of the\n> project. I'm merely trying to think about worst-case scenarios, which\n> may or may not be helpful in this context.\n\nNo problem (I also like to think worst-case scenarios, so thanks for the\nthought experiment).\n\nInitially I agreed with the concerns you raised, but on further thinking\nI don't have the same concerns any more, for two reasons.\n\n (1) It's impossible to tell if someone is actually intentionally\n sabotaging the interests of a competitor --- simply because no one\n will admit to doing so openly on this list.\n\n (2) Even if we do have authority figures on this project, if they\n block a patch series from being merged, the reasons they give must\n remain purely technical. Otherwise, I think such authority figures\n will compromise (lose) their reputation pretty quickly.\n\nFor (2) it could be that they could block something for both $DAYJOB and\ntechnical reasons, but I think this is still fine. The fact that they\nhave $DAYJOB reasons wouldn't take away any merit from the technical\nreasons.\n"}]}