From 2a663045351eeb74b8f84e82f073f1e681263152 Mon Sep 17 00:00:00 2001
From: Mathieu Othacehe <othacehe@gnu.org>
Date: Wed, 7 Sep 2022 17:05:00 +0200
Subject: etc: teams: Add scope support.

Add a scope list to each team.  This list defines all the files and
directories that are mentored by the team.

Also add a cc-members command that takes two Git revision strings as input,
add returns the members that should be CC'ed given the files impacted between
the two revisions.

* etc/teams.scm.in (<team>)[scope]: New field.
(team, list-teams): Adapt those procedures.
(find-team-by-scope, diff-revisions): New procedures.
(main): Add a "cc-members" command.
* doc/contributing.texi ("Teams"): Document it.
("Sending a Patch Series"): Adapt it.
---
 doc/contributing.texi | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

(limited to 'doc')

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 17a54f94cc..7712f63d67 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1406,6 +1406,47 @@ for more information.  You can install @command{git send-email} with
 @command{guix install git:send-email}.
 @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
 
+To maximize the chances that you patch series is reviewed, the preferred
+submission way is to use the @code{etc/teams.scm} script to notify the
+appropriate team members (@pxref{Teams}).
+
+@unnumberedsubsec Teams
+@anchor{Teams}
+@cindex teams
+
+There are several teams mentoring different parts of the Guix source
+code.  To list all those teams, you can run from a Guix checkout:
+
+@example
+$ ./etc/teams.scm list-teams
+id: mentors
+name: Mentors
+description: A group of mentors who chaperone contributions by newcomers.
+members:
++ Christopher Baines <mail@@cbaines.net>
++ Ricardo Wurmus <rekado@@elephly.net>
++ Mathieu Othacehe <othacehe@@gnu.org>
++ jgart <jgart@@dismail.de>
++ Ludovic Courtès <ludo@@gnu.org>
+@dots{}
+@end example
+
+You can run the following command to have the @code{Mentors} team put in
+CC of a patch series:
+
+@example
+$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
+@end example
+
+The appropriate team or teams can also be inferred from the modified
+files.  For instance, if you want to send the two latest commits of the
+current Git repository to review, you can run:
+
+@example
+$ guix shell -D guix
+[env]$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
+@end example
+
 @node Tracking Bugs and Patches
 @section Tracking Bugs and Patches
 
-- 
cgit 1.4.1