[PATCH v2] doc: describe the project's decision-making process

From

Josh Steadmon <steadmon@google.com>

Date

May 9, 2024, 00:01 UTC

Message-ID

<4a829792bf16973799bf3b3db0dd8b49a1ef3815.1715212665.git.steadmon@google.com>

In-Reply-To

<b2ef74c1b0c7482fa880a1519fd6ea1032df7789.1713222673.git.steadmon@google.com>

Signed-off-by: Josh Steadmon <steadmon@google.com>
---

Changes in V2:
* Split doc to treat patch series discussion as the general case, with
  larger discussions (with or without patches) as special situations.
* Add links to example discussions for certain situations
* Add link to contributor summit notes
* Add link to Code of Conduct
* Add justification for keeping discussion on-list
* Add paragraph about explicit negative consensus
* Minor reword of advice on when to CC experts
* Minor reword of doc intro to avoid indecisive text

 Documentation/DecisionMaking.txt | 122 +++++++++++++++++++++++++++++++
 Documentation/Makefile           |   1 +
 2 files changed, 123 insertions(+)
 create mode 100644 Documentation/DecisionMaking.txt

diff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt
new file mode 100644
index 0000000000..55fa3e2185
--- /dev/null
+++ b/Documentation/DecisionMaking.txt
@@ -0,0 +1,122 @@
+Decision-Making Process in the Git Project
+==========================================
+
+Introduction
+------------
+This doc aims to describe the current decision-making process in the Git
+project. It is a descriptive rather than prescriptive doc; that is, we want to
+describe how things work in practice rather than explicitly recommending any
+particular process or changes to the current process.
+
+Here we document how the project makes decisions for general patch series, and
+for larger-scale discussions (with or without patches).
+
+
+General Patch Series
+--------------------
+
+Starting a Discussion
+~~~~~~~~~~~~~~~~~~~~~
+For most changes, discussions are started by sending a patch series to the list.
+There is rarely any need to discuss or ask for approval prior to sending
+patches; the merit of both the general idea behind your change and the code to
+implement it will be discussed at the same time.
+
+NOTE: For general guides on creating and sending a patch series to the list, see
+link:SubmittingPatches.html[SubmittingPatches] and
+link:MyFirstContribution.html[MyFirstContribution]. The remainder of this
+doc will focus more on what to expect from the list discussion.
+
+Because members of the Git community have a wide variety of experience,
+backgrounds, and values, series are expected to include as much context as
+possible.
+
+If the proposer is aware of individuals with an interest in the subject of the
+change, it is helpful to CC them on the proposal to increase the likelihood of
+receiving constructive feedback.
+
+Engaging in Discussion
+~~~~~~~~~~~~~~~~~~~~~~
+Once a proposal has been made, the community will discuss it on-list. While the
+maintainer will often participate in discussions, it is not the maintainer's
+responsibility to guide discussion; the proposer and any other interested
+parties are expected to stay engaged in the discussion and ensure progress is
+made.
+
+Anyone with an interest in the topic is welcome to discuss the matter. It is
+expected that all discussion will adhere to the link:../CODE_OF_CONDUCT.md[Code
+of Conduct] rules.
+
+Finalizing a Decision
+~~~~~~~~~~~~~~~~~~~~~
+If the maintainer judges that positive consensus has been reached on a topic,
+they will merge the series, usually to the 'next' integration branch. After a
+suitable period of time for testing by the community, changes are merged from
+'next' into 'master', from which official releases are tagged.
+
+If consensus has not been reached, discussion may continue, or the proposal may
+be abandoned if no one continues discussion. More rarely, explicit negative
+consensus may be reached if the community feels that the series is not suitable,
+in which case the series should be dropped and discussion ended.
+
+There are no strict guidelines used to judge when consensus has been reached,
+but generally we expect all points of feedback to have been addressed with
+either a fix or an explanation on why no change is necessary.
+
+
+Larger Discussions (with patches)
+---------------------------------
+As with discussions on a general patch series, starting a larger-scale
+discussion often begins by sending a patch or series to the list. This might
+take the form of an initial design doc, with implementation following in later
+iterations of the series (for example,
+link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding
+unit tests] or
+link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based
+hooks]), or it might include a full implementation from the beginning. In either
+case, discussion progresses as described above until consensus is reached or the
+topic is dropped.
+
+
+Larger Discussions (without patches)
+------------------------------------
+Occasionally, larger discussions might occur without an associated patch series.
+These might be very large-scale technical decisions that are beyond the scope of
+even a single large patch series, or they might be more open-ended,
+policy-oriented discussions (examples:
+link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust]
+or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving
+submodule UX]). In either case, discussion progresses as described above for
+general patch series.
+
+For larger discussions without a patch series or other concrete implementation,
+it may be hard to judge when consensus has been reached, as there are not any
+official guidelines. If discussion stalls at this point, it may be helpful to
+restart discussion with an RFC patch series or other specific implementation
+that can be more easily debated.
+
+If consensus around a decision has been reached but no implementation provided,
+it is not the maintainer's responsibility to implement any particular decision.
+For decisions that require code changes, it is often the case that the original
+proposer will follow up with a patch series, although it is also common for
+other interested parties to provide an implementation (or parts of the
+implementation, for very large changes).
+
+For non-technical decisions such as community norms or processes, it is up to
+the community as a whole to implement and sustain agreed-upon changes.
+
+
+Other Discussion Venues
+-----------------------
+Occasionally decision proposals are presented off-list, e.g. at the semi-regular
+Contributors' Summit. While higher-bandwidth face-to-face discussion is often
+useful for quickly reaching consensus among attendees, generally we expect to
+summarize the discussion in notes that can later be presented on-list. For an
+example, see the thread
+link:https://lore.kernel.org/git/AC2EB721-2979-43FD-922D-C5076A57F24B@jramsay.com.au/[Notes
+from Git Contributor Summit, Los Angeles (April 5, 2020)] by James Ramsay.
+
+We prefer that "official" discussion happens on the list so that the full
+community has opportunity to engage in discussion. This also means that the
+mailing list archives contain a more-or-less complete history of project
+discussions and decisions.
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 3f2383a12c..a04da672c6 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -103,6 +103,7 @@ SP_ARTICLES += howto/coordinate-embargoed-releases
 API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
 SP_ARTICLES += $(API_DOCS)
 
+TECH_DOCS += DecisionMaking
 TECH_DOCS += ReviewingGuidelines
 TECH_DOCS += MyFirstContribution
 TECH_DOCS += MyFirstObjectWalk

base-commit: 436d4e5b14df49870a897f64fe92c0ddc7017e4c

-- 
2.45.0.rc1.225.g2a3ae87e7f-goog