[bug#72891] [PATCH RFC] doc: Define the purpose, membership, and creation of teams.

["Ludovic Courtès" <ludo@gnu.org>]

* doc/contributing.texi (Teams): Define the purpose of teams; provide
example; clarify membership and team creation.
(Reviewing the Work of Others): Link to “Teams”.

Change-Id: I5d75f69bc4653eb9da9c1d1f920718238ea83b9d
---
 doc/contributing.texi | 63 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 53 insertions(+), 10 deletions(-)

Hello Guix!

The recent discussion about creating a browser team¹ made it clear
that teams are not defined anywhere: the manual doesn’t say what their
mission is, how to become a member, how to revoke members, nor how
to create new teams.

This patch is an attempt to formalize that.  I believe there’s nothing
really new for someone who’s been following closely in recent times, but
it should definitely improve legibility for newcomers.

Thoughts?

I suggest that we iterate on this for at most one month so we have a
first version checked in by September 30th.

Ludo’.

¹ https://lists.gnu.org/archive/html/guix-devel/2024-08/msg00168.html

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 73f7addbef..7705367bce 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -2225,8 +2225,52 @@ Teams
 @subsection 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:
+To organize work on Guix, including but not just development efforts,
+the project has a set of @dfn{teams}.  Each team has its own focus and
+interests and is the primary contact point for questions and
+contributions in those areas.  A team's primary mission is to coordinate
+and review the work of individuals in its scope (@pxref{Reviewing the
+Work of Others}); it can make decisions within its scope, in agreement
+with other teams whenever there is overlap or a close connection, and in
+accordance with other project rules such as seeking consensus.
+@c TODO: Currently ``consensus-based decision making'' is discussed
+@c under ``Commit Access''.  Move that elsewhere and refer to it from
+@c here.
+
+As an example, the Python team is responsible for core Python packaging
+matters; it can decide to upgrade core Python packages in a dedicated
+@code{python-team} branch, in collaboration with any team whose scope is
+directly dependent on Python---e.g., the Science team---and following
+branching rules (@pxref{Managing Patches and Branches}).  The
+Documentation team helps review changes to the documentation and can
+initiate overarching documentation changes.  The Translations team
+organizes translation of Guix and its manual and coordinates efforts in
+that area.  The Core team is responsible for the development of core
+functionality and interfaces of Guix; because of its central nature,
+some of its work may require soliciting input from the community at
+large and seeking consensus before enacting decisions that would affect
+the entire community.
+
+Teams are defined in the @file{etc/teams.scm} file in the Guix
+repository.  The scope of each team is defined, when applicable, as a
+set of files or as a regular expression matching file names.
+
+@cindex team membership
+Anyone with interest in a team's domain and willing to contribute to its
+work can apply to become a member by contacting current members by
+email; commit access is not a precondition.  Membership is formalized by
+adding the person's name and email address to @file{etc/teams.scm}.
+Members who have not been participating in the team's work for one year
+or more may be removed; they are free to reapply for membership later.
+
+@cindex team creation
+One or more people may propose the creation of a new team by reaching
+out to the community by email at @email{guix-devel@@gnu.org}, clarifying
+the intended scope and purpose.  When consensus is reached on the
+creation of this team, someone with commit access formalizes its
+creation by adding it and its initial members to @file{etc/teams.scm}.
+
+To list existing teams, run the following command from a Guix checkout:
 
 @example
 $ ./etc/teams.scm list-teams
@@ -2234,15 +2278,12 @@ Teams
 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>
++ Charlie Smith <charlie@@example.org>
 @dots{}
 @end example
 
-You can run the following command to have the @code{Mentors} team put in
+@cindex mentoring
+You can run the following command to have the Mentors team put in
 CC of a patch series:
 
 @example
@@ -2905,12 +2946,14 @@ Reviewing the Work of Others
 is to review the work contributed by others.  You do not need to be a
 committer to do so; applying, reading the source, building, linting and
 running other people's series and sharing your comments about your
-experience will give some confidence to committers.  Basically, you must
+experience will give some confidence to committers.  You must
 ensure the check list found in the @ref{Submitting Patches} section has
 been correctly followed.  A reviewed patch series should give the best
 chances for the proposed change to be merged faster, so if a change you
 would like to see merged hasn't yet been reviewed, this is the most
-appropriate thing to do!
+appropriate thing to do!  If you would like to review changes in a
+specific area and to receive notifications for incoming patches relevant
+to that domain, consider joining the relevant team(s) (@pxref{Teams}).
 
 @cindex reviewing, guidelines
 Review comments should be unambiguous; be as clear and explicit as you

base-commit: d5312370b46ace47e138d84e1bb28e5651cee94b
-- 
2.45.2