* [RFC PATCH] doc: describe the project's decision-making process
@ 2024-04-15 23:20 Josh Steadmon
2024-04-16 0:24 ` Junio C Hamano
` (2 more replies)
0 siblings, 3 replies; 16+ messages in thread
From: Josh Steadmon @ 2024-04-15 23:20 UTC (permalink / raw)
To: git; +Cc: avarab, christian.couder, gitster, me
The Git project currently operates according to informal, unstated norms
when it comes to making bigger-picture decisions (above and beyond
individual patches and patch series). Document these norms so that
newcomers to the project can learn what to expect.
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 <steadmon@google.com>
---
This doc represents my impression of how the community operates. I have
obviously not been around as long as many other community members, so I
would welcome feedback if you feel that this misses or misrepresents any
aspect of how we make decisions.
One particular blind spot for me is how the Project Leadership Committee
operates, or if that's even relevant to this doc.
Unfortunately, I will be away from the list for a few days for $LIFE
reasons, but I will try to address feedback promptly once I get back.
Documentation/DecisionMaking.txt | 58 ++++++++++++++++++++++++++++++++
Documentation/Makefile | 1 +
2 files changed, 59 insertions(+)
create mode 100644 Documentation/DecisionMaking.txt
diff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt
new file mode 100644
index 0000000000..80fc732551
--- /dev/null
+++ b/Documentation/DecisionMaking.txt
@@ -0,0 +1,58 @@
+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.
+
+We want to describe how the project makes larger-scale decisions. We won't be
+discussing how decisions are made for individual patches or patch series,
+although the process is similar at a high level.
+
+Starting a Discussion
+---------------------
+Proposals are made on the mailing list. Because members of the Git community
+have a wide variety of experience, backgrounds, and values, proposals are
+expected to include as much context as possible.
+
+If the proposer is aware of individuals with an interest in the topic being
+discussed, it is polite to CC them on the proposal to make sure they are aware
+of the discussion.
+
+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 Code of Conduct rules.
+
+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, so that
+the full community has opportunity to engage in discussion.
+
+Finalizing a Decision
+---------------------
+After a suitable period of time has passed, the maintainer will judge whether or
+not consensus has been reached. If so, the consensus decision will be
+implemented. Otherwise, discussion may continue, or the proposal may be
+abandoned.
+
+In general, 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 make the necessary changes to implement the
+decision, although it is also common for other interested parties to provide an
+implementation.
+
+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.
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.44.0.683.g7961c838ac-goog
^ permalink raw reply related [flat|nested] 16+ messages in thread
* Re: [RFC PATCH] doc: describe the project's decision-making process
2024-04-15 23:20 [RFC PATCH] doc: describe the project's decision-making process Josh Steadmon
@ 2024-04-16 0:24 ` Junio C Hamano
2024-04-22 21:10 ` Josh Steadmon
2024-04-17 16:32 ` Enrico Mrass
2024-04-22 18:41 ` Emily Shaffer
2 siblings, 1 reply; 16+ messages in thread
From: Junio C Hamano @ 2024-04-16 0:24 UTC (permalink / raw)
To: Josh Steadmon; +Cc: git, avarab, christian.couder, me
Josh Steadmon <steadmon@google.com> writes:
> The Git project currently operates according to informal, unstated norms
> when it comes to making bigger-picture decisions (above and beyond
> individual patches and patch series). Document these norms so that
> newcomers to the project can learn what to expect.
It would be a good idea to write things down to help newcomers, but
the thing is, that we do not do that kind of design discussion +
design review + implementaiton waterfall here very often (a notable
exception was the sha256 transition design). I am afraid that
"according to informal unstated norms" is an overstatement. We do
not have any "process" concrete, nothing more than concensus
building among amicable parties.
Most of the time, technical decisions are made on individual series
and by the time the consensus is reached on the series that it is
good, the implementation should be finished, and there is no
separate "implementation" step. Newcomers would probably want to
become familiar with that part of the decision process before
joining the "big picture" discussion, I suspect.
> One particular blind spot for me is how the Project Leadership Committee
> operates, or if that's even relevant to this doc.
I think this is the part PLC@SFC is supposed to be of relevance:
> +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.
> +Anyone with an interest in the topic is welcome to discuss the matter. It is
> +expected that all discussion will adhere to the Code of Conduct rules.
It is very much worth mentioning CoC here.
> 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
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [RFC PATCH] doc: describe the project's decision-making process
2024-04-15 23:20 [RFC PATCH] doc: describe the project's decision-making process Josh Steadmon
2024-04-16 0:24 ` Junio C Hamano
@ 2024-04-17 16:32 ` Enrico Mrass
2024-04-17 16:58 ` Junio C Hamano
2024-04-22 18:41 ` Emily Shaffer
2 siblings, 1 reply; 16+ messages in thread
From: Enrico Mrass @ 2024-04-17 16:32 UTC (permalink / raw)
To: steadmon; +Cc: avarab, christian.couder, git, gitster, me
Josh Steadmon <steadmon@google.com> writes:
> Document these norms so that newcomers to the project can learn what to
> expect.
As a newcomer (first reply to the list), I highly appreciate the effort. Thank you!
> +After a suitable period of time has passed, the maintainer will judge whether or
> +not consensus has been reached. If so, the consensus decision will be
> +implemented. Otherwise, discussion may continue, or the proposal may be
> +abandoned.
I'd be curious to learn about norms or practices applied when no consensus
could be reached. It seems worth elaborating on that as part of documenting the
decision-making process.
> making bigger-picture decisions (above and beyond individual patches and
> patch series)
I understand how bigger-picture decisions (complex, larger scale architectural
decisions, often involving multiple components, likely requiring a design
discussion / review) are different from individual patches. However, nothing
in the current description strikes me as specific to these larger-scale
decisions. Are there norms / practices that specifically address challenges
around large-scale changes that are worth documenting here, like encouraging
a design for discussion in the first place?
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [RFC PATCH] doc: describe the project's decision-making process
2024-04-17 16:32 ` Enrico Mrass
@ 2024-04-17 16:58 ` Junio C Hamano
2024-05-03 14:45 ` Junio C Hamano
0 siblings, 1 reply; 16+ messages in thread
From: Junio C Hamano @ 2024-04-17 16:58 UTC (permalink / raw)
To: Enrico Mrass; +Cc: steadmon, avarab, christian.couder, git, me
Enrico Mrass <emrass@google.com> writes:
> I'd be curious to learn about norms or practices applied when no consensus
> could be reached. It seems worth elaborating on that as part of documenting the
> decision-making process.
I may be forgetting things, but I do not know if there is a concrete
"here is a norm that we have been using to reach a consensus, not
just written down but it has been there" in the first place, let
alone "here is what we do to resolve an irreconcilable differences".
"We discuss and try to reach a consensus in an amicable way,
sticking to CoC, etc." has mostly been good enough for our happy
family, perhaps?
> ... However, nothing
> in the current description strikes me as specific to these larger-scale
> decisions.
I agree with that.
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [RFC PATCH] doc: describe the project's decision-making process
2024-04-15 23:20 [RFC PATCH] doc: describe the project's decision-making process Josh Steadmon
2024-04-16 0:24 ` Junio C Hamano
2024-04-17 16:32 ` Enrico Mrass
@ 2024-04-22 18:41 ` Emily Shaffer
2024-04-22 19:18 ` Junio C Hamano
2024-04-23 1:10 ` Junio C Hamano
2 siblings, 2 replies; 16+ messages in thread
From: Emily Shaffer @ 2024-04-22 18:41 UTC (permalink / raw)
To: Josh Steadmon; +Cc: git, avarab, christian.couder, gitster, me
On Mon, Apr 15, 2024 at 4:20 PM Josh Steadmon <steadmon@google.com> wrote:
>
> The Git project currently operates according to informal, unstated norms
> when it comes to making bigger-picture decisions (above and beyond
> individual patches and patch series). Document these norms so that
> newcomers to the project can learn what to expect.
>
> 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.
Thanks for writing this. I, for one, would love to see the process
evolve a little to account for the scale of work coming through the
list on any given day. However, that's a discussion that will be
easier to have once we have the status quo written and checked in.
Last week I attended Open Source Summit North America, and one
recurring theme I heard at many of the talks about project governance
and scalability was that every type of governance comes with cost
attached; one of the costs of a model as informal as ours is that it
takes time to explain over and over how we make decisions, as long as
it's not documented. I actually see this quite often, when we have
someone write in to the list or the Discord asking for permission to
implement a feature, or whether a given change would be welcome.
So, if nobody disagrees with the content of this document, I think we
should absolutely merge it. It will be great for newbies to see what
they're getting into, and for me to send to my boss to explain why my
predictions for my team's patches landing are so broad.
>
> Signed-off-by: Josh Steadmon <steadmon@google.com>
See review below. I had a few small nits, but with or without those
changes, it looks good to me.
Reviewed-by: Emily Shaffer <nasamuffin@google.com>
> ---
> This doc represents my impression of how the community operates. I have
> obviously not been around as long as many other community members, so I
> would welcome feedback if you feel that this misses or misrepresents any
> aspect of how we make decisions.
>
> One particular blind spot for me is how the Project Leadership Committee
> operates, or if that's even relevant to this doc.
>
> Unfortunately, I will be away from the list for a few days for $LIFE
> reasons, but I will try to address feedback promptly once I get back.
>
> Documentation/DecisionMaking.txt | 58 ++++++++++++++++++++++++++++++++
> Documentation/Makefile | 1 +
> 2 files changed, 59 insertions(+)
> create mode 100644 Documentation/DecisionMaking.txt
>
> diff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt
> new file mode 100644
> index 0000000000..80fc732551
> --- /dev/null
> +++ b/Documentation/DecisionMaking.txt
> @@ -0,0 +1,58 @@
> +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.
> +
> +We want to describe how the project makes larger-scale decisions. We won't be
> +discussing how decisions are made for individual patches or patch series,
> +although the process is similar at a high level.
Nit: "We want to" still sounds like something that goes in the patch
description. If I imagine this doc checked in, I'd rather it says
"that is, it describes how..." or "This doc attempts to describe
how..."
As you mentioned elsewhere, it seems like the process isn't so
different between smaller patches and large-scale designs - does that
mean it makes more sense to take out the large-scale disclaimer and
leave notes on which steps you can omit for simpler proposals?
> +
> +Starting a Discussion
> +---------------------
> +Proposals are made on the mailing list. Because members of the Git community
> +have a wide variety of experience, backgrounds, and values, proposals are
> +expected to include as much context as possible.
Could it be worth making this more explicit? Or pointing to similar
guidelines from SubmittingPatches? For example, I think we like to
understand where the need is coming from - is there a user base in
mind for this large-scale thing? Is it solving a scaling problem for
you somehow? These are things we ask for from cover letters, too.
> +
> +If the proposer is aware of individuals with an interest in the topic being
> +discussed, it is polite to CC them on the proposal to make sure they are aware
> +of the discussion.
What about "it is a good idea to CC them on the proposal to make sure
they're aware of the discussion, and let them know you're interested
in their thoughts"? Or some other way to point out that CCing people
this way also increases the chance of a lively discussion?
For later,
> +
> +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.
Yes, I like very much that this is called out. I don't think this is
something someone would expect - not all project maintainers operate
this way, so we should document it for our project.
> +
> +Anyone with an interest in the topic is welcome to discuss the matter. It is
> +expected that all discussion will adhere to the Code of Conduct rules.
I wouldn't mind seeing an explicit link to the CoC in our source tree from here.
> +
> +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, so that
> +the full community has opportunity to engage in discussion.
Could you say why? Between the lines and with my experience with the
project I can understand that that's because the mailing list is The
place for communication, and all official decisionmaking happens here.
But since we're documenting how decisions happen, it seems worth
calling out explicitly that they must happen on this list.
It could also be nice to link to one of the great note writeups from
contributor summits past as an example.
> +
> +Finalizing a Decision
> +---------------------
> +After a suitable period of time has passed, the maintainer will judge whether or
> +not consensus has been reached. If so, the consensus decision will be
> +implemented. Otherwise, discussion may continue, or the proposal may be
> +abandoned.
I think this captures the status quo. But I'm also left saying,
"indefinitely?! how do we tell people 'thanks, but no thanks'?" Maybe
something we can discuss after this patch lands :)
> +
> +In general, 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 make the necessary changes to implement the
> +decision, although it is also common for other interested parties to provide an
> +implementation.
> +
> +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.
> 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.44.0.683.g7961c838ac-goog
>
>
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [RFC PATCH] doc: describe the project's decision-making process
2024-04-22 18:41 ` Emily Shaffer
@ 2024-04-22 19:18 ` Junio C Hamano
2024-04-22 21:12 ` Emily Shaffer
2024-04-23 1:10 ` Junio C Hamano
1 sibling, 1 reply; 16+ messages in thread
From: Junio C Hamano @ 2024-04-22 19:18 UTC (permalink / raw)
To: Emily Shaffer; +Cc: Josh Steadmon, git, avarab, christian.couder, me
Emily Shaffer <nasamuffin@google.com> writes:
> Thanks for writing this. I, for one, would love to see the process
> evolve a little to account for the scale of work coming through the
> list on any given day. However, that's a discussion that will be
> easier to have once we have the status quo written and checked in.
> ...
> So, if nobody disagrees with the content of this document, I think we
> should absolutely merge it. It will be great for newbies to see what
> they're getting into, and for me to send to my boss to explain why my
> predictions for my team's patches landing are so broad.
Isn't it a bit too late to say "if nobody disagrees with", after it
was pointed out that the world around here does not work that way
(yet) about a week ago?
If we have an agreeable v2 already posted on the list that I missed,
then sorry, please disregard the above comment.
I still don't think it captures "the status quo", which is what you
want this document to be, about "larger-scale decisions", as the
Introduction of the document says. Can we have a set of pointers in
the document, when it gets rerolled, to an actual example of how we
made such a larger-scale decision? Without such illustration with a
real world example, it looks to me that what it describes is what we
wish the process to be (which is not necessarily I would object to),
but labeling it as "describing the status quo" is very much
objectionable.
Thanks.
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [RFC PATCH] doc: describe the project's decision-making process
2024-04-16 0:24 ` Junio C Hamano
@ 2024-04-22 21:10 ` Josh Steadmon
2024-04-22 21:30 ` Junio C Hamano
0 siblings, 1 reply; 16+ messages in thread
From: Josh Steadmon @ 2024-04-22 21:10 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, avarab, christian.couder, me
On 2024.04.15 17:24, Junio C Hamano wrote:
> Josh Steadmon <steadmon@google.com> writes:
>
> > The Git project currently operates according to informal, unstated norms
> > when it comes to making bigger-picture decisions (above and beyond
> > individual patches and patch series). Document these norms so that
> > newcomers to the project can learn what to expect.
>
> It would be a good idea to write things down to help newcomers, but
> the thing is, that we do not do that kind of design discussion +
> design review + implementaiton waterfall here very often (a notable
> exception was the sha256 transition design). I am afraid that
> "according to informal unstated norms" is an overstatement. We do
> not have any "process" concrete, nothing more than concensus
> building among amicable parties.
>
> Most of the time, technical decisions are made on individual series
> and by the time the consensus is reached on the series that it is
> good, the implementation should be finished, and there is no
> separate "implementation" step. Newcomers would probably want to
> become familiar with that part of the decision process before
> joining the "big picture" discussion, I suspect.
Yes, as I noted in the doc (but need to emphasize), I'm not intending to
describe day-to-day patch review here. I'm thinking more of larger-scale
discussions such as "Introducing Rust into the Git project" [1] or the
spinoff discussion "Defining a platform support policy" [2].
[1] https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/
[2] https://lore.kernel.org/git/CAJoAoZnHGTFhfR6e6r=GMSfVbSNgLoHF-opaWYLbHppiuzi+Rg@mail.gmail.com/
While clearly nothing has been decided on those topics, it seems to me
at least that they follow a pattern of "discussion now, consensus
(hopefully) soon, implementation later".
Or do you think it's more accurate to say that we rarely/never make
decisions without patches? Does that mean it's pointless to start a
discussion without a patch series attached? I'm trying to decide whether
it's worth editing this doc for V2, or just starting over with a much
smaller one instead.
> > One particular blind spot for me is how the Project Leadership Committee
> > operates, or if that's even relevant to this doc.
>
> I think this is the part PLC@SFC is supposed to be of relevance:
>
> > +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.
>
> > +Anyone with an interest in the topic is welcome to discuss the matter. It is
> > +expected that all discussion will adhere to the Code of Conduct rules.
>
> It is very much worth mentioning CoC here.
>
> > 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
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [RFC PATCH] doc: describe the project's decision-making process
2024-04-22 19:18 ` Junio C Hamano
@ 2024-04-22 21:12 ` Emily Shaffer
0 siblings, 0 replies; 16+ messages in thread
From: Emily Shaffer @ 2024-04-22 21:12 UTC (permalink / raw)
To: Junio C Hamano
Cc: Josh Steadmon, git, avarab, christian.couder, me,
brian m. carlson
On Mon, Apr 22, 2024 at 12:18 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Emily Shaffer <nasamuffin@google.com> writes:
>
> > Thanks for writing this. I, for one, would love to see the process
> > evolve a little to account for the scale of work coming through the
> > list on any given day. However, that's a discussion that will be
> > easier to have once we have the status quo written and checked in.
> > ...
> > So, if nobody disagrees with the content of this document, I think we
> > should absolutely merge it. It will be great for newbies to see what
> > they're getting into, and for me to send to my boss to explain why my
> > predictions for my team's patches landing are so broad.
>
> Isn't it a bit too late to say "if nobody disagrees with", after it
> was pointed out that the world around here does not work that way
> (yet) about a week ago?
Well, so far we heard from one person who perceives it as status quo
(the author), one person new to the project, the maintainer, and me :)
I think Josh is working on a v2 with links as you asked.
I have certainly followed the process Josh described here for a couple
of large projects coming from my team - to mind, config-based hooks,
submodules UX proposal, and libification proposal all came with
discussion before any patches. I'd love to hear from others who have
been implementing large-scale changes in a different way, like brian,
or Taylor and the other GitHub folks, too - if this patch is too
different from what actually happens with their work, let's trim until
it isn't, instead.
>
> If we have an agreeable v2 already posted on the list that I missed,
> then sorry, please disregard the above comment.
>
> I still don't think it captures "the status quo", which is what you
> want this document to be, about "larger-scale decisions", as the
> Introduction of the document says. Can we have a set of pointers in
> the document, when it gets rerolled, to an actual example of how we
> made such a larger-scale decision? Without such illustration with a
> real world example, it looks to me that what it describes is what we
> wish the process to be (which is not necessarily I would object to),
> but labeling it as "describing the status quo" is very much
> objectionable.
>
> Thanks.
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [RFC PATCH] doc: describe the project's decision-making process
2024-04-22 21:10 ` Josh Steadmon
@ 2024-04-22 21:30 ` Junio C Hamano
2024-04-23 22:41 ` Junio C Hamano
0 siblings, 1 reply; 16+ messages in thread
From: Junio C Hamano @ 2024-04-22 21:30 UTC (permalink / raw)
To: Josh Steadmon; +Cc: git, avarab, christian.couder, me
Josh Steadmon <steadmon@google.com> writes:
> While clearly nothing has been decided on those topics, it seems to me
> at least that they follow a pattern of "discussion now, consensus
> (hopefully) soon, implementation later".
>
> Or do you think it's more accurate to say that we rarely/never make
> decisions without patches?
As I said, I do think it is rare for us to start with only "ideas"
without anything concrete to comment on, and that is why I asked
some references (e.g., URLs into the archive) to a discussion in the
past of a larger decisions where (1) something is proposed, (2)
discussed, and (3) declaration that a consensus has reached, if a
document describes the status quo.
> Does that mean it's pointless to start a
> discussion without a patch series attached?
It does not necessarily mean it is not worth trying to do it more
often that we have done it rarely.
Is it desirable to make more larger decisions to implement changes
that take longer effort and deeper commitments? As long as we can
have a meaningful discussion, the "anything concrete to comment on"
I mentioned earlier in the previous paragraph does not have to be a
patch series.
> I'm trying to decide whether it's worth editing this doc for V2,
> or just starting over with a much smaller one instead.
And if the lack of documented process is a factor that contributes
to the rarity of such decisions, it is a reasonable goal to have a
documented process. And learning from past sucesses (and failures)
by starting a document that describes the status quo is a good idea.
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [RFC PATCH] doc: describe the project's decision-making process
2024-04-22 18:41 ` Emily Shaffer
2024-04-22 19:18 ` Junio C Hamano
@ 2024-04-23 1:10 ` Junio C Hamano
1 sibling, 0 replies; 16+ messages in thread
From: Junio C Hamano @ 2024-04-23 1:10 UTC (permalink / raw)
To: Emily Shaffer; +Cc: Josh Steadmon, git, avarab, christian.couder, me
Emily Shaffer <nasamuffin@google.com> writes:
>> +Finalizing a Decision
>> +---------------------
>> +After a suitable period of time has passed, the maintainer will judge whether or
>> +not consensus has been reached. If so, the consensus decision will be
>> +implemented. Otherwise, discussion may continue, or the proposal may be
>> +abandoned.
>
> I think this captures the status quo. But I'm also left saying,
> "indefinitely?! how do we tell people 'thanks, but no thanks'?"
Wouldn't telling people "Thanks, but no thanks" count as a
consensus, which happens once a consensus to discard the proposal
has reached?
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [RFC PATCH] doc: describe the project's decision-making process
2024-04-22 21:30 ` Junio C Hamano
@ 2024-04-23 22:41 ` Junio C Hamano
0 siblings, 0 replies; 16+ messages in thread
From: Junio C Hamano @ 2024-04-23 22:41 UTC (permalink / raw)
To: Josh Steadmon; +Cc: git, avarab, christian.couder, me
Junio C Hamano <gitster@pobox.com> writes:
> As I said, I do think it is rare for us to start with only "ideas"
> without anything concrete to comment on, and that is why I asked
> some references (e.g., URLs into the archive) to a discussion in the
> past of a larger decisions where (1) something is proposed, (2)
> discussed, and (3) declaration that a consensus has reached, if a
> document describes the status quo.
FYI, what I readily recall was the discussion that started here.
https://lore.kernel.org/git/20170304011251.GA26789@aiede.mtv.corp.google.com/
It did have a few iterations and then near the end the consensus has
turned into a "patch" that adds the design document to our history,
but otherwise, it did not involve a "series" level patch reviews.
HTH..
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [RFC PATCH] doc: describe the project's decision-making process
2024-04-17 16:58 ` Junio C Hamano
@ 2024-05-03 14:45 ` Junio C Hamano
2024-05-03 15:48 ` Josh Steadmon
0 siblings, 1 reply; 16+ messages in thread
From: Junio C Hamano @ 2024-05-03 14:45 UTC (permalink / raw)
To: git; +Cc: steadmon, avarab, christian.couder, me, Enrico Mrass,
Emily Shaffer
Junio C Hamano <gitster@pobox.com> writes:
> Enrico Mrass <emrass@google.com> writes:
>
>> I'd be curious to learn about norms or practices applied when no consensus
>> could be reached. It seems worth elaborating on that as part of documenting the
>> decision-making process.
>
> I may be forgetting things, but I do not know if there is a concrete
> "here is a norm that we have been using to reach a consensus, not
> just written down but it has been there" in the first place, let
> alone "here is what we do to resolve an irreconcilable differences".
>
> "We discuss and try to reach a consensus in an amicable way,
> sticking to CoC, etc." has mostly been good enough for our happy
> family, perhaps?
>
>> ... However, nothing
>> in the current description strikes me as specific to these larger-scale
>> decisions.
>
> I agree with that.
We didn't hear any more comments on this topic, but writing down how
the world works around here, with the goal to eventually have a set
of project governance rules, is valuable. Otherwise loud people may
act according to their own (unwritten) rules that annoy others and
harm the community.
Thanks.
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [RFC PATCH] doc: describe the project's decision-making process
2024-05-03 14:45 ` Junio C Hamano
@ 2024-05-03 15:48 ` Josh Steadmon
2024-05-03 18:08 ` Junio C Hamano
0 siblings, 1 reply; 16+ messages in thread
From: Josh Steadmon @ 2024-05-03 15:48 UTC (permalink / raw)
To: Junio C Hamano
Cc: git, avarab, christian.couder, me, Enrico Mrass, Emily Shaffer
Yes, sorry for silence on this thread. I am working on a V2 but
probably won't have it ready today.
On Fri, May 3, 2024 at 7:45 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> Junio C Hamano <gitster@pobox.com> writes:
>
> > Enrico Mrass <emrass@google.com> writes:
> >
> >> I'd be curious to learn about norms or practices applied when no consensus
> >> could be reached. It seems worth elaborating on that as part of documenting the
> >> decision-making process.
> >
> > I may be forgetting things, but I do not know if there is a concrete
> > "here is a norm that we have been using to reach a consensus, not
> > just written down but it has been there" in the first place, let
> > alone "here is what we do to resolve an irreconcilable differences".
> >
> > "We discuss and try to reach a consensus in an amicable way,
> > sticking to CoC, etc." has mostly been good enough for our happy
> > family, perhaps?
> >
> >> ... However, nothing
> >> in the current description strikes me as specific to these larger-scale
> >> decisions.
> >
> > I agree with that.
>
> We didn't hear any more comments on this topic, but writing down how
> the world works around here, with the goal to eventually have a set
> of project governance rules, is valuable. Otherwise loud people may
> act according to their own (unwritten) rules that annoy others and
> harm the community.
>
> Thanks.
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [RFC PATCH] doc: describe the project's decision-making process
2024-05-03 15:48 ` Josh Steadmon
@ 2024-05-03 18:08 ` Junio C Hamano
2024-05-03 19:29 ` Taylor Blau
0 siblings, 1 reply; 16+ messages in thread
From: Junio C Hamano @ 2024-05-03 18:08 UTC (permalink / raw)
To: Josh Steadmon
Cc: git, avarab, christian.couder, me, Enrico Mrass, Emily Shaffer
Josh Steadmon <steadmon@google.com> writes:
> On Fri, May 3, 2024 at 7:45 AM Junio C Hamano <gitster@pobox.com> wrote:
>>
>> We didn't hear any more comments on this topic, but writing down how
>> the world works around here, with the goal to eventually have a set
>> of project governance rules, is valuable. Otherwise loud people may
>> act according to their own (unwritten) rules that annoy others and
>> harm the community.
[jc: do not top post].
> Yes, sorry for silence on this thread. I am working on a V2 but
> probably won't have it ready today.
Don't be sorry; the message was not addressed to you, but for wider
community participants---especially the ones with more "clout" (or
"long timers" or whatever word we would use to describe those whose
opinions are trusted by others and count more) need to buy in if we
were to first agree on that it is good to have a set of written
rules, and to then agree on what rules to adopt.
We might want to pick ideas from https://fossgovernance.org/ for
example.
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [RFC PATCH] doc: describe the project's decision-making process
2024-05-03 18:08 ` Junio C Hamano
@ 2024-05-03 19:29 ` Taylor Blau
2024-05-06 7:12 ` Patrick Steinhardt
0 siblings, 1 reply; 16+ messages in thread
From: Taylor Blau @ 2024-05-03 19:29 UTC (permalink / raw)
To: Junio C Hamano
Cc: Josh Steadmon, git, avarab, christian.couder, Enrico Mrass,
Emily Shaffer
On Fri, May 03, 2024 at 11:08:15AM -0700, Junio C Hamano wrote:
> > Yes, sorry for silence on this thread. I am working on a V2 but
> > probably won't have it ready today.
>
> Don't be sorry; the message was not addressed to you, but for wider
> community participants---especially the ones with more "clout" (or
> "long timers" or whatever word we would use to describe those whose
> opinions are trusted by others and count more) need to buy in if we
> were to first agree on that it is good to have a set of written
> rules, and to then agree on what rules to adopt.
I have been meaning to respond to this thread since I was mentioned in
it by Emily, but have been unsure of what to say.
On one hand, I think the document basically outlines the status-quo of
decision making for issues that are larger than the scope of a single
patch series (think "should we use Rust?", "what is our platform
support policy?", or "how should we approach libification?" not "is this
particular patch (series) correct?").
So in that sense, I think that the document is a good starting point,
and I think that it reasonably captures the status quo.
But I wish that we didn't have to have such a document in the first
place. In my opinion, I would much rather see decisions like "what is
our platform policy?" made according to discussions on a patch that
defines what that policy is. That way such decisions can be treated in
the same way as ordinary review is today, and we can avoid the need for
a separate process.
(For what it's worth, I thought that the SHA-256 transition was a good
example of this. The RFC was posted, and the discussion was had on the
patch series itself).
Another way of thinking about this is that I would be extremely
reluctant to see a similar document proposed for reviewing at the patch
series level. In my opinion, the system of reviewers and participants
discussing the series and the maintainer solely determining whether or
not consensus has been reached is a good one, and I would be extremely
hesitant to recommend changing it.
And I would advocate for a similar approach to decisions that have
implications beyond a single patch series.
Thanks,
Taylor
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [RFC PATCH] doc: describe the project's decision-making process
2024-05-03 19:29 ` Taylor Blau
@ 2024-05-06 7:12 ` Patrick Steinhardt
0 siblings, 0 replies; 16+ messages in thread
From: Patrick Steinhardt @ 2024-05-06 7:12 UTC (permalink / raw)
To: Taylor Blau
Cc: Junio C Hamano, Josh Steadmon, git, avarab, christian.couder,
Enrico Mrass, Emily Shaffer
[-- Attachment #1: Type: text/plain, Size: 5030 bytes --]
On Fri, May 03, 2024 at 03:29:13PM -0400, Taylor Blau wrote:
> On Fri, May 03, 2024 at 11:08:15AM -0700, Junio C Hamano wrote:
> > > Yes, sorry for silence on this thread. I am working on a V2 but
> > > probably won't have it ready today.
> >
> > Don't be sorry; the message was not addressed to you, but for wider
> > community participants---especially the ones with more "clout" (or
> > "long timers" or whatever word we would use to describe those whose
> > opinions are trusted by others and count more) need to buy in if we
> > were to first agree on that it is good to have a set of written
> > rules, and to then agree on what rules to adopt.
Fair enough. Given that I have been contributing quite a bit more
recently I'll feel myself addressed here.
> I have been meaning to respond to this thread since I was mentioned in
> it by Emily, but have been unsure of what to say.
>
> On one hand, I think the document basically outlines the status-quo of
> decision making for issues that are larger than the scope of a single
> patch series (think "should we use Rust?", "what is our platform
> support policy?", or "how should we approach libification?" not "is this
> particular patch (series) correct?").
>
> So in that sense, I think that the document is a good starting point,
> and I think that it reasonably captures the status quo.
>
> But I wish that we didn't have to have such a document in the first
> place. In my opinion, I would much rather see decisions like "what is
> our platform policy?" made according to discussions on a patch that
> defines what that policy is. That way such decisions can be treated in
> the same way as ordinary review is today, and we can avoid the need for
> a separate process.
With "such a document", do you refer to the one documenting the process
to do such changes or the RFC-style document?
If you mean the former I disagree and think that it would be great to
document reasonable approaches for how to get to an agreement with the
Git community. It's especially helpful for newcomers to the commuinity,
and I do get questions around "How to reach consensus in Git" all the
time at GitLab.
Now the important part to me is that we should retain flexibility and
allow us to adapt. It should rather be a helpful resource to newcomers
than a rigid set of requirements that everyone has to follow, in my
opinion.
If it's the latter (no need for an RFC-style document) I somewhat agree.
I'm of the opinion that patches are the best way to trigger a more
informed discussion because participants will know how something will
end up looking like. I also tend to send patch series for controversial
topics upstream without prior discussion, but my intent here is never to
force the result, but rather to force the discussion itself. This of
course comes with the big downside that you may end up wasting quite a
lot of your own time in case the community disagrees with your approach,
but that's acceptable to me most of the time.
It's only part of the story though. There are bigger changes that simply
don't make a ton of sense to propose in the above form, mostly because
their sheer scope is much larger. As you point out further down, things
like the SHA256 transition are in that realm.
Here I very much think that having a central place where such large
projects are tracked. Given that we have no issue tracker, I think the
next-best place to do this would be the Git repository itself. We
already do this for some larger topics, but I feel like the bar is quite
high right now. It doesn't make a ton of sense for example to have a
huge RFC for the removal of `the_repository`.
So something that I'd really love to see is if we adopted the micro
projects document [1] into Git itself and generalized it such that we
can add smallish sections for new large-scale projects. Ideally, such
projects could also have trailers that indicate who is interested in
those projects such that folks knew whom to reach out to if they want to
start contributing to the project. This would help us to document
consensus around new projects, and would help newcomers of the
community to pick up new projects.
Patrick
[1]: https://git.github.io/SoC-2024-Microprojects/
> (For what it's worth, I thought that the SHA-256 transition was a good
> example of this. The RFC was posted, and the discussion was had on the
> patch series itself).
>
> Another way of thinking about this is that I would be extremely
> reluctant to see a similar document proposed for reviewing at the patch
> series level. In my opinion, the system of reviewers and participants
> discussing the series and the maintainer solely determining whether or
> not consensus has been reached is a good one, and I would be extremely
> hesitant to recommend changing it.
>
> And I would advocate for a similar approach to decisions that have
> implications beyond a single patch series.
>
> Thanks,
> Taylor
>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 16+ messages in thread
end of thread, other threads:[~2024-05-06 7:12 UTC | newest]
Thread overview: 16+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-04-15 23:20 [RFC PATCH] doc: describe the project's decision-making process Josh Steadmon
2024-04-16 0:24 ` Junio C Hamano
2024-04-22 21:10 ` Josh Steadmon
2024-04-22 21:30 ` Junio C Hamano
2024-04-23 22:41 ` Junio C Hamano
2024-04-17 16:32 ` Enrico Mrass
2024-04-17 16:58 ` Junio C Hamano
2024-05-03 14:45 ` Junio C Hamano
2024-05-03 15:48 ` Josh Steadmon
2024-05-03 18:08 ` Junio C Hamano
2024-05-03 19:29 ` Taylor Blau
2024-05-06 7:12 ` Patrick Steinhardt
2024-04-22 18:41 ` Emily Shaffer
2024-04-22 19:18 ` Junio C Hamano
2024-04-22 21:12 ` Emily Shaffer
2024-04-23 1:10 ` Junio C Hamano
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).