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

* 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

1 files changed, 53 insertions, 10 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 48524c9dac..acdc303be6 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -2226,8 +2226,52 @@ revision, and these changes are necessary.
 @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
@@ -2235,15 +2279,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
@@ -2911,12 +2952,14 @@ Perhaps the biggest action you can do to help GNU Guix grow as a project
 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