[bug#73803] [PATCH 0/2] Add "Decision Making" section

[bug#73803] [PATCH 0/2] Add "Decision Making" section

[Ludovic Courtès]

Hello,

As Simon proposed in <https://issues.guix.gnu.org/72891>, these patches
move the paragraphs about consensus seeking to a section of its own
called “Decision Making”.  It also promotes the new “Teams” section.

Thoughts?

Ludo’.

Ludovic Courtès (2):
  doc: Add “Making Decisions” section.
  doc: Promote “Teams” section.

 doc/contributing.texi | 197 ++++++++++++++++++++++--------------------
 1 file changed, 104 insertions(+), 93 deletions(-)


base-commit: 6757bfdfc0b22a1e23a3d33566155550182244fc
-- 
2.46.0

[bug#73803] [PATCH 1/2] doc: Add “Making Decisions” section.

[Ludovic Courtès]

Suggested by Simon Tournier <zimon.toutoune@gmail.com>.

* doc/contributing.texi (Making Decisions): New section, with paragraphs
moved from…
(Commit Access): … here.  Cross-reference it.
(Teams): Likewise.

Change-Id: Ib276242e0ec7598a1b60dacdde8647bd3d3b85d3
---
 doc/contributing.texi | 45 +++++++++++++++++++++++++++----------------
 1 file changed, 28 insertions(+), 17 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index acdc303be6..cc6e84013a 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -31,6 +31,7 @@ Contributing
 * Coding Style::                Hygiene of the contributor.
 * Submitting Patches::          Share your work.
 * Tracking Bugs and Changes::   Keeping it all organized.
+* Making Decisions::            Collectively choosing the way forward.
 * Commit Access::               Pushing to the official repository.
 * Reviewing the Work of Others::  Some guidelines for sharing reviews.
 * Updating the Guix Package::   Updating the Guix package definition.
@@ -2233,10 +2234,8 @@ Teams
 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.
+accordance with other project rules such as seeking consensus
+(@pxref{Making Decisions}).
 
 As an example, the Python team is responsible for core Python packaging
 matters; it can decide to upgrade core Python packages in a dedicated
@@ -2706,6 +2705,25 @@ Cuirass Build Notifications
 where each RSS entry contains a link to the Cuirass build details page
 of the associated build.
 
+@node Making Decisions
+@section Making Decisions
+
+@cindex decision making
+@cindex consensus seeking
+It is expected from all contributors, and even more so from committers,
+to help build consensus and make decisions based on consensus.  By using
+consensus, we are committed to finding solutions that everyone can live
+with.  It implies that no decision is made against significant concerns
+and these concerns are actively resolved with proposals that work for
+everyone.
+
+A contributor (who may or may not have commit access) wishing to block
+a proposal bears a special responsibility for finding alternatives,
+proposing ideas/code or explain the rationale for the status quo to
+resolve the deadlock.  To learn what consensus decision making means and
+understand its finer details, you are encouraged to read
+@url{https://www.seedsforchange.org.uk/consensus}.
+
 @node Commit Access
 @section Commit Access
 
@@ -2721,19 +2739,10 @@ Commit Access
 thought of as a ``badge of honor'' but rather as a responsibility a
 contributor is willing to take to help the project.
 
-It is expected from all contributors, and even more so from committers,
-to help build consensus and make decisions based on consensus.  By using
-consensus, we are committed to finding solutions that everyone can live
-with.  It implies that no decision is made against significant concerns
-and these concerns are actively resolved with proposals that work for
-everyone.
-
-A contributor (who may or may not have commit access) wishing to block
-a proposal bears a special responsibility for finding alternatives,
-proposing ideas/code or explain the rationale for the status quo to
-resolve the deadlock.  To learn what consensus decision making means and
-understand its finer details, you are encouraged to read
-@url{https://www.seedsforchange.org.uk/consensus}.
+Committers are in a position where they enact technical decisions.  Such
+decisions must be made by @emph{actively building consensus} among
+interested parties and stakeholders.  @ref{Making Decisions}, for more
+on that.
 
 The following sections explain how to get commit access, how to be ready
 to push commits, and the policies and community expectations for commits
@@ -3006,6 +3015,8 @@ Reviewing the Work of Others
 the project to keep bikes dry.}.  As a reviewer, try hard to explain the
 rationale for suggestions you make, and to understand and take into
 account the submitter's motivation for doing things in a certain way.
+In other words, build consensus with everyone involved (@pxref{Making
+Decisions}).
 @end enumerate
 
 @cindex LGTM, Looks Good To Me
-- 
2.46.0

[bug#73803] [PATCH 2/2] doc: Promote “Teams” section.

[Ludovic Courtès]

Suggested by Simon Tournier <zimon.toutoune@gmail.com>.

* doc/contributing.texi (Teams): Move from subsection of “Submitting
Patches” to section of “Contributing”.

Change-Id: Id21be29380fc981e74a5025b1467eebde8566726
---
 doc/contributing.texi | 156 +++++++++++++++++++++---------------------
 1 file changed, 78 insertions(+), 78 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index cc6e84013a..0385cedfb1 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -31,6 +31,7 @@ Contributing
 * Coding Style::                Hygiene of the contributor.
 * Submitting Patches::          Share your work.
 * Tracking Bugs and Changes::   Keeping it all organized.
+* Teams::                       Coordinating efforts.
 * Making Decisions::            Collectively choosing the way forward.
 * Commit Access::               Pushing to the official repository.
 * Reviewing the Work of Others::  Some guidelines for sharing reviews.
@@ -2055,7 +2056,6 @@ Submitting Patches
 @menu
 * Configuring Git::
 * Sending a Patch Series::
-* Teams::
 @end menu
 
 @node Configuring Git
@@ -2223,83 +2223,6 @@ Sending a Patch Series
 another cover letter, e.g. for explaining what's changed since the last
 revision, and these changes are necessary.
 
-@node Teams
-@subsection Teams
-@cindex teams
-
-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{Making Decisions}).
-
-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
-id: mentors
-name: Mentors
-description: A group of mentors who chaperone contributions by newcomers.
-members:
-+ Charlie Smith <charlie@@example.org>
-@dots{}
-@end example
-
-@cindex mentoring
-You can run the following command to have the Mentors team put in
-CC of a patch series:
-
-@example
-$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \
-  --header-cmd='etc/teams.scm cc-mentors-header-cmd' *.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=@var{ISSUE_NUMBER}@@debbugs.gnu.org -2
-@end example
-
 @node Tracking Bugs and Changes
 @section Tracking Bugs and Changes
 
@@ -2705,6 +2628,83 @@ Cuirass Build Notifications
 where each RSS entry contains a link to the Cuirass build details page
 of the associated build.
 
+@node Teams
+@section Teams
+@cindex teams
+
+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{Making Decisions}).
+
+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
+id: mentors
+name: Mentors
+description: A group of mentors who chaperone contributions by newcomers.
+members:
++ Charlie Smith <charlie@@example.org>
+@dots{}
+@end example
+
+@cindex mentoring
+You can run the following command to have the Mentors team put in
+CC of a patch series:
+
+@example
+$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \
+  --header-cmd='etc/teams.scm cc-mentors-header-cmd' *.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=@var{ISSUE_NUMBER}@@debbugs.gnu.org -2
+@end example
+
 @node Making Decisions
 @section Making Decisions
 
-- 
2.46.0