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

Commit Message

Josh Steadmon May 9, 2024, 12:01 a.m. UTC

The Git project currently operates according to an informal
consensus-building process, which is not currently well-described.
Document what to expect so that we have something concrete to help
inform newcomers to the project.

This document explicitly does not aim to impose a formal process to
decision-making, nor to change pre-existing norms. Its only aim is to
describe how the project currently operates today.

Signed-off-by: Josh Steadmon <[e-mail]>
---

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


base-commit: 436d4e5b14df49870a897f64fe92c0ddc7017e4c

Comments

Junio C Hamano May 9, 2024, 6:10 p.m. UTC | #1

Josh Steadmon <[e-mail]> writes:

> 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

It might not be yet ready to claim this, but when it gets ready to
do so, we would want to say "aims to describe" -> "describes".

> +General Patch Series
> +--------------------

As if there is a separate section for "Special Patch Series"?  But
more seriously, I cannot quite shake this feeling that most of these
are covered in the beginning of the SubmittingPatches document.
There probably are small things that are missing over there that can
be found here, but given the large overlap, I have a feeling that
these additions are better done over there, not here, and limit the
scope of this document to decisions beyond the "General" patch
series.  There already is SubmittingPatches::[[patch-flow]] section
that may be a better place for the material we see here.

> +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.

We do not say "you need no permission or pre-approval" which may be
a good thing to add to SubmittingPatches.

> +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.

So my question is if there is anything of substance left we should
have here, or if it is better to add them to SubmittingPatches so
that readers need to read one fewer documents.

> +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.

SubmittingPatches::[[describe-changes]] and [[patch-flow]] might be
a better home for some sentences stolen from here?

> +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.

Ditto for the above to SubmittingPatches::[[send-patches]] and [[patch-flow]]?

> +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.

Ditto for the above to SubmittingPatches::[[patch-flow]]?


> +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/[e-mail]/[adding
> +unit tests] or
> +link:https://lore.kernel.org/git/[e-mail]/[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.

OK.

> +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/[e-mail]/[introducing Rust]
> +or link:https://lore.kernel.org/git/[e-mail]/[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.

As it is not anybody's responsibility, it may be confusing to single
the maintainer out in this sentence.  Saying "it is not" alone will
leave readers wondering "then whose responsibility is it?".  

I would say:

    When consensus is reached that it is a good idea, the original
    proposer is expected to coordinate the effort to make it happen,
    with help from others who were involved in the discussion as
    needed.

without pretending that the issues that needs consensus are black
and white "requiring code changes" vs "non-technical" without any
other colors.  IOW, I'd drop the following two paragraphs, as the
above would be sufficient.

> +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/[e-mail]/[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.

OK.

Thanks.

Junio C Hamano May 9, 2024, 7:20 p.m. UTC | #2

Junio C Hamano <[e-mail]> writes:

> There probably are small things that are missing over there that can
> be found here, but given the large overlap, I have a feeling that
> these additions are better done over there, not here, and limit the
> scope of this document to decisions beyond the "General" patch
> series.  There already is SubmittingPatches::[[patch-flow]] section
> that may be a better place for the material we see here.

To see how well this approach can go, I plan to spend some time
today reorganizing SubmittingPatches and enhancing some descriptions
in it.  The plan is roughly

 * Add a preamble to explain "why" you would want to send, and we
   would want to receive, patches in a larger picture.

 * Move [[patch-flow]] section to the very beginning, with a bit of
   enhanced description on the review cycle, i.e. what patches,
   their review comments, and review responses are expected to
   contain and for what goal.

 * Possibly remove things from other sections that would become
   redundant by the enhancement above.

Patch

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/[e-mail]/[adding
+unit tests] or
+link:https://lore.kernel.org/git/[e-mail]/[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/[e-mail]/[introducing Rust]
+or link:https://lore.kernel.org/git/[e-mail]/[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/[e-mail]/[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