(address . guix-patches@gnu.org)(name . Ludovic Courtès)(address . ludo@gnu.org)
fb9721adfc71b841dcb6a2575539449ce756e401.1725012038.git.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’.
Toggle diff (99 lines)
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