doc: Define the purpose, membership, and creation of teams.issue-72891

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

1 files changed, 48 insertions, 8 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 06edaef77d..af2c044f71 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -2871,8 +2871,51 @@ contributors, too!
 @section 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
+(@pxref{Consensus Decision}).
+
+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.  Other said, teams provide feedback on patches
+touching its scope (@pxref{Reviewing the Work of Others}).
+
+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
@@ -2880,15 +2923,12 @@ 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>
++ 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