Subject: Re: [PATCH v3] doc: describe the project's decision-making process

From: Patrick Steinhardt <[email-masked]>
Date: Fri, 17 May 2024 08:29:45 +0200

On Thu, May 16, 2024 at 02:20:53PM -0700, Josh Steadmon wrote:
[snip]
> diff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt
> new file mode 100644
> index 0000000000..274ddfa62c
> --- /dev/null
> +++ b/Documentation/DecisionMaking.txt
> @@ -0,0 +1,74 @@
> +Decision-Making Process in the Git Project
> +==========================================
> +
> +Introduction
> +------------
> +This document describes 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.

Nit: I think we _do_ want to recommend a process, but don't want to cast
it into stone.

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

One thing I want to eventually propose is to go further here:
documenting the outcome of the discussion, regardless of whether we
decided for or against it, in a low-overhead format. This could for
example be a small paragraph in a "Documentation/Projects" file that
points to the on-list discussion together with a small summary of why
the decision was reached.

In the case of the Rust discussion for example I think we ultimately
decided against it due to platform limitations of the toolchain. This
limitation will potentially go away at some point in time, and that
would allow us to revisit this discussion. Now if we had documented
somewhere that the decision against Rust was platform support, then it
is easy to revive the discussion at a later point and point to that
exact reason, arguing why it's not longer a problem now.

I don't think that this change needs to be part of your patch though, as
your intent is only to document processes as they work right now. But I
wanted to bring this up regardless as a foreshadowing.

Overall this document looks good to me, thanks!

Patrick