{"thread":{"id":"61325","subject":"[RFC PATCH] doc: describe the project's decision-making process","startedAt":"2024-04-15T23:20:08Z","lastAt":"2024-05-21T05:58:17Z","messageCount":44,"participants":["Josh Steadmon","Junio C Hamano","Enrico Mrass","Emily Shaffer","Taylor Blau","Patrick Steinhardt","Karthik Nayak"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"492971","messageId":"b2ef74c1b0c7482fa880a1519fd6ea1032df7789.1713222673.git.steadmon@google.com","threadId":"61325","inReplyTo":null,"subject":"[RFC PATCH] doc: describe the project's decision-making process","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2024-04-15T23:20:05Z","receivedAt":"2024-04-15T23:20:08Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"The Git project currently operates according to informal, unstated norms\nwhen it comes to making bigger-picture decisions (above and beyond\nindividual patches and patch series). Document these norms so that\nnewcomers to the project can learn what to expect.\n\nThis document explicitly does not aim to impose a formal process to\ndecision-making, nor to change pre-existing norms. Its only aim is to\ndescribe how the project currently operates today.\n\nSigned-off-by: Josh Steadmon <steadmon@google.com>\n---\nThis doc represents my impression of how the community operates. I have\nobviously not been around as long as many other community members, so I\nwould welcome feedback if you feel that this misses or misrepresents any\naspect of how we make decisions.\n\nOne particular blind spot for me is how the Project Leadership Committee\noperates, or if that's even relevant to this doc.\n\nUnfortunately, I will be away from the list for a few days for $LIFE\nreasons, but I will try to address feedback promptly once I get back.\n\n Documentation/DecisionMaking.txt | 58 ++++++++++++++++++++++++++++++++\n Documentation/Makefile           |  1 +\n 2 files changed, 59 insertions(+)\n create mode 100644 Documentation/DecisionMaking.txt\n\ndiff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt\nnew file mode 100644\nindex 0000000000..80fc732551\n--- /dev/null\n+++ b/Documentation/DecisionMaking.txt\n@@ -0,0 +1,58 @@\n+Decision-Making Process in the Git Project\n+==========================================\n+\n+Introduction\n+------------\n+This doc aims to describe the current decision-making process in the Git\n+project. It is a descriptive rather than prescriptive doc; that is, we want to\n+describe how things work in practice rather than explicitly recommending any\n+particular process or changes to the current process.\n+\n+We want to describe how the project makes larger-scale decisions. We won't be\n+discussing how decisions are made for individual patches or patch series,\n+although the process is similar at a high level.\n+\n+Starting a Discussion\n+---------------------\n+Proposals are made on the mailing list. Because members of the Git community\n+have a wide variety of experience, backgrounds, and values, proposals are\n+expected to include as much context as possible.\n+\n+If the proposer is aware of individuals with an interest in the topic being\n+discussed, it is polite to CC them on the proposal to make sure they are aware\n+of the discussion.\n+\n+Engaging in Discussion\n+----------------------\n+Once a proposal has been made, the community will discuss it on-list. While the\n+maintainer will often participate in discussions, it is not the maintainer's\n+responsibility to guide discussion; the proposer and any other interested\n+parties are expected to stay engaged in the discussion and ensure progress is\n+made.\n+\n+Anyone with an interest in the topic is welcome to discuss the matter. It is\n+expected that all discussion will adhere to the Code of Conduct rules.\n+\n+Other Discussion Venues\n+~~~~~~~~~~~~~~~~~~~~~~~\n+Occasionally decision proposals are presented off-list, e.g. at the semi-regular\n+Contributors' Summit. While higher-bandwidth face-to-face discussion is often\n+useful for quickly reaching consensus among attendees, generally we expect to\n+summarize the discussion in notes that can later be presented on-list, so that\n+the full community has opportunity to engage in discussion.\n+\n+Finalizing a Decision\n+---------------------\n+After a suitable period of time has passed, the maintainer will judge whether or\n+not consensus has been reached. If so, the consensus decision will be\n+implemented. Otherwise, discussion may continue, or the proposal may be\n+abandoned.\n+\n+In general, it is not the maintainer's responsibility to implement any\n+particular decision. For decisions that require code changes, it is often the\n+case that the original proposer will make the necessary changes to implement the\n+decision, although it is also common for other interested parties to provide an\n+implementation.\n+\n+For non-technical decisions such as community norms or processes, it is up to\n+the community as a whole to implement and sustain agreed-upon changes.\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3f2383a12c..a04da672c6 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -103,6 +103,7 @@ SP_ARTICLES += howto/coordinate-embargoed-releases\n API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))\n SP_ARTICLES += $(API_DOCS)\n \n+TECH_DOCS += DecisionMaking\n TECH_DOCS += ReviewingGuidelines\n TECH_DOCS += MyFirstContribution\n TECH_DOCS += MyFirstObjectWalk\n\nbase-commit: 436d4e5b14df49870a897f64fe92c0ddc7017e4c\n-- \n2.44.0.683.g7961c838ac-goog\n\n"},{"id":"492974","messageId":"xmqq34rmi28h.fsf@gitster.g","threadId":"61325","inReplyTo":"b2ef74c1b0c7482fa880a1519fd6ea1032df7789.1713222673.git.steadmon@google.com","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-04-16T00:24:14Z","receivedAt":"2024-04-16T00:24:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Josh Steadmon <steadmon@google.com> writes:\n\n> The Git project currently operates according to informal, unstated norms\n> when it comes to making bigger-picture decisions (above and beyond\n> individual patches and patch series). Document these norms so that\n> newcomers to the project can learn what to expect.\n\nIt would be a good idea to write things down to help newcomers, but\nthe thing is, that we do not do that kind of design discussion +\ndesign review + implementaiton waterfall here very often (a notable\nexception was the sha256 transition design).  I am afraid that\n\"according to informal unstated norms\" is an overstatement.  We do\nnot have any \"process\" concrete, nothing more than concensus\nbuilding among amicable parties.\n\nMost of the time, technical decisions are made on individual series\nand by the time the consensus is reached on the series that it is\ngood, the implementation should be finished, and there is no\nseparate \"implementation\" step.  Newcomers would probably want to\nbecome familiar with that part of the decision process before\njoining the \"big picture\" discussion, I suspect.\n\n> One particular blind spot for me is how the Project Leadership Committee\n> operates, or if that's even relevant to this doc.\n\nI think this is the part PLC@SFC is supposed to be of relevance:\n\n> +For non-technical decisions such as community norms or processes, it is up to\n> +the community as a whole to implement and sustain agreed-upon changes.\n\n> +Anyone with an interest in the topic is welcome to discuss the matter. It is\n> +expected that all discussion will adhere to the Code of Conduct rules.\n\nIt is very much worth mentioning CoC here.\n\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 3f2383a12c..a04da672c6 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -103,6 +103,7 @@ SP_ARTICLES += howto/coordinate-embargoed-releases\n>  API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))\n>  SP_ARTICLES += $(API_DOCS)\n>  \n> +TECH_DOCS += DecisionMaking\n>  TECH_DOCS += ReviewingGuidelines\n>  TECH_DOCS += MyFirstContribution\n>  TECH_DOCS += MyFirstObjectWalk\n>\n> base-commit: 436d4e5b14df49870a897f64fe92c0ddc7017e4c\n"},{"id":"493100","messageId":"20240417163244.651791-1-emrass@google.com","threadId":"61325","inReplyTo":"b2ef74c1b0c7482fa880a1519fd6ea1032df7789.1713222673.git.steadmon@google.com","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Enrico Mrass","fromEmail":"emrass@google.com","sentAt":"2024-04-17T16:32:44Z","receivedAt":"2024-04-17T16:32:46Z","isPatch":true,"sender":{"key":"emrass@google.com","avatar":null},"body":"Josh Steadmon <steadmon@google.com> writes:\n\n> Document these norms so that newcomers to the project can learn what to\n> expect.\n\nAs a newcomer (first reply to the list), I highly appreciate the effort. Thank you!\n\n> +After a suitable period of time has passed, the maintainer will judge whether or\n> +not consensus has been reached. If so, the consensus decision will be\n> +implemented. Otherwise, discussion may continue, or the proposal may be\n> +abandoned.\n\nI'd be curious to learn about norms or practices applied when no consensus\ncould be reached. It seems worth elaborating on that as part of documenting the\ndecision-making process.\n\n> making bigger-picture decisions (above and beyond individual patches and\n> patch series)\n\nI understand how bigger-picture decisions (complex, larger scale architectural\ndecisions, often involving multiple components, likely requiring a design\ndiscussion / review) are different from individual patches. However, nothing\nin the current description strikes me as specific to these larger-scale\ndecisions. Are there norms / practices that specifically address challenges\naround large-scale changes that are worth documenting here, like encouraging\na design for discussion in the first place?\n"},{"id":"493103","messageId":"xmqqr0f47wp9.fsf@gitster.g","threadId":"61325","inReplyTo":"20240417163244.651791-1-emrass@google.com","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-04-17T16:58:26Z","receivedAt":"2024-04-17T16:58:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Enrico Mrass <emrass@google.com> writes:\n\n> I'd be curious to learn about norms or practices applied when no consensus\n> could be reached. It seems worth elaborating on that as part of documenting the\n> decision-making process.\n\nI may be forgetting things, but I do not know if there is a concrete\n\"here is a norm that we have been using to reach a consensus, not\njust written down but it has been there\" in the first place, let\nalone \"here is what we do to resolve an irreconcilable differences\".\n\n\"We discuss and try to reach a consensus in an amicable way,\nsticking to CoC, etc.\" has mostly been good enough for our happy\nfamily, perhaps?\n\n> ... However, nothing\n> in the current description strikes me as specific to these larger-scale\n> decisions.\n\nI agree with that.\n"},{"id":"493314","messageId":"CAJoAoZmOqEd9HcHMrOUwSXNJi2a8DLeO_11gW1h_HuaK79WEVg@mail.gmail.com","threadId":"61325","inReplyTo":"b2ef74c1b0c7482fa880a1519fd6ea1032df7789.1713222673.git.steadmon@google.com","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Emily Shaffer","fromEmail":"nasamuffin@google.com","sentAt":"2024-04-22T18:41:43Z","receivedAt":"2024-04-22T18:41:57Z","isPatch":true,"sender":{"key":"nasamuffin@google.com","avatar":"https://avatars.githubusercontent.com/u/1606826?v=4"},"body":"On Mon, Apr 15, 2024 at 4:20 PM Josh Steadmon <steadmon@google.com> wrote:\n>\n> The Git project currently operates according to informal, unstated norms\n> when it comes to making bigger-picture decisions (above and beyond\n> individual patches and patch series). Document these norms so that\n> newcomers to the project can learn what to expect.\n>\n> This document explicitly does not aim to impose a formal process to\n> decision-making, nor to change pre-existing norms. Its only aim is to\n> describe how the project currently operates today.\n\nThanks for writing this. I, for one, would love to see the process\nevolve a little to account for the scale of work coming through the\nlist on any given day. However, that's a discussion that will be\neasier to have once we have the status quo written and checked in.\n\nLast week I attended Open Source Summit North America, and one\nrecurring theme I heard at many of the talks about project governance\nand scalability was that every type of governance comes with cost\nattached; one of the costs of a model as informal as ours is that it\ntakes time to explain over and over how we make decisions, as long as\nit's not documented. I actually see this quite often, when we have\nsomeone write in to the list or the Discord asking for permission to\nimplement a feature, or whether a given change would be welcome.\n\nSo, if nobody disagrees with the content of this document, I think we\nshould absolutely merge it. It will be great for newbies to see what\nthey're getting into, and for me to send to my boss to explain why my\npredictions for my team's patches landing are so broad.\n\n>\n> Signed-off-by: Josh Steadmon <steadmon@google.com>\n\nSee review below. I had a few small nits, but with or without those\nchanges, it looks good to me.\n\nReviewed-by: Emily Shaffer <nasamuffin@google.com>\n\n> ---\n> This doc represents my impression of how the community operates. I have\n> obviously not been around as long as many other community members, so I\n> would welcome feedback if you feel that this misses or misrepresents any\n> aspect of how we make decisions.\n>\n> One particular blind spot for me is how the Project Leadership Committee\n> operates, or if that's even relevant to this doc.\n>\n> Unfortunately, I will be away from the list for a few days for $LIFE\n> reasons, but I will try to address feedback promptly once I get back.\n>\n>  Documentation/DecisionMaking.txt | 58 ++++++++++++++++++++++++++++++++\n>  Documentation/Makefile           |  1 +\n>  2 files changed, 59 insertions(+)\n>  create mode 100644 Documentation/DecisionMaking.txt\n>\n> diff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt\n> new file mode 100644\n> index 0000000000..80fc732551\n> --- /dev/null\n> +++ b/Documentation/DecisionMaking.txt\n> @@ -0,0 +1,58 @@\n> +Decision-Making Process in the Git Project\n> +==========================================\n> +\n> +Introduction\n> +------------\n> +This doc aims to describe the current decision-making process in the Git\n> +project. It is a descriptive rather than prescriptive doc; that is, we want to\n> +describe how things work in practice rather than explicitly recommending any\n> +particular process or changes to the current process.\n> +\n> +We want to describe how the project makes larger-scale decisions. We won't be\n> +discussing how decisions are made for individual patches or patch series,\n> +although the process is similar at a high level.\n\nNit: \"We want to\" still sounds like something that goes in the patch\ndescription. If I imagine this doc checked in, I'd rather it says\n\"that is, it describes how...\" or \"This doc attempts to describe\nhow...\"\n\nAs you mentioned elsewhere, it seems like the process isn't so\ndifferent between smaller patches and large-scale designs - does that\nmean it makes more sense to take out the large-scale disclaimer and\nleave notes on which steps you can omit for simpler proposals?\n\n> +\n> +Starting a Discussion\n> +---------------------\n> +Proposals are made on the mailing list. Because members of the Git community\n> +have a wide variety of experience, backgrounds, and values, proposals are\n> +expected to include as much context as possible.\n\nCould it be worth making this more explicit? Or pointing to similar\nguidelines from SubmittingPatches? For example, I think we like to\nunderstand where the need is coming from - is there a user base in\nmind for this large-scale thing? Is it solving a scaling problem for\nyou somehow? These are things we ask for from cover letters, too.\n\n> +\n> +If the proposer is aware of individuals with an interest in the topic being\n> +discussed, it is polite to CC them on the proposal to make sure they are aware\n> +of the discussion.\n\nWhat about \"it is a good idea to CC them on the proposal to make sure\nthey're aware of the discussion, and let them know you're interested\nin their thoughts\"? Or some other way to point out that CCing people\nthis way also increases the chance of a lively discussion?\n\nFor later,\n\n> +\n> +Engaging in Discussion\n> +----------------------\n> +Once a proposal has been made, the community will discuss it on-list. While the\n> +maintainer will often participate in discussions, it is not the maintainer's\n> +responsibility to guide discussion; the proposer and any other interested\n> +parties are expected to stay engaged in the discussion and ensure progress is\n> +made.\n\nYes, I like very much that this is called out. I don't think this is\nsomething someone would expect - not all project maintainers operate\nthis way, so we should document it for our project.\n\n> +\n> +Anyone with an interest in the topic is welcome to discuss the matter. It is\n> +expected that all discussion will adhere to the Code of Conduct rules.\n\nI wouldn't mind seeing an explicit link to the CoC in our source tree from here.\n\n> +\n> +Other Discussion Venues\n> +~~~~~~~~~~~~~~~~~~~~~~~\n> +Occasionally decision proposals are presented off-list, e.g. at the semi-regular\n> +Contributors' Summit. While higher-bandwidth face-to-face discussion is often\n> +useful for quickly reaching consensus among attendees, generally we expect to\n> +summarize the discussion in notes that can later be presented on-list, so that\n> +the full community has opportunity to engage in discussion.\n\nCould you say why? Between the lines and with my experience with the\nproject I can understand that that's because the mailing list is The\nplace for communication, and all official decisionmaking happens here.\nBut since we're documenting how decisions happen, it seems worth\ncalling out explicitly that they must happen on this list.\n\nIt could also be nice to link to one of the great note writeups from\ncontributor summits past as an example.\n\n> +\n> +Finalizing a Decision\n> +---------------------\n> +After a suitable period of time has passed, the maintainer will judge whether or\n> +not consensus has been reached. If so, the consensus decision will be\n> +implemented. Otherwise, discussion may continue, or the proposal may be\n> +abandoned.\n\nI think this captures the status quo. But I'm also left saying,\n\"indefinitely?! how do we tell people 'thanks, but no thanks'?\" Maybe\nsomething we can discuss after this patch lands :)\n\n> +\n> +In general, it is not the maintainer's responsibility to implement any\n> +particular decision. For decisions that require code changes, it is often the\n> +case that the original proposer will make the necessary changes to implement the\n> +decision, although it is also common for other interested parties to provide an\n> +implementation.\n> +\n> +For non-technical decisions such as community norms or processes, it is up to\n> +the community as a whole to implement and sustain agreed-upon changes.\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 3f2383a12c..a04da672c6 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -103,6 +103,7 @@ SP_ARTICLES += howto/coordinate-embargoed-releases\n>  API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))\n>  SP_ARTICLES += $(API_DOCS)\n>\n> +TECH_DOCS += DecisionMaking\n>  TECH_DOCS += ReviewingGuidelines\n>  TECH_DOCS += MyFirstContribution\n>  TECH_DOCS += MyFirstObjectWalk\n>\n> base-commit: 436d4e5b14df49870a897f64fe92c0ddc7017e4c\n> --\n> 2.44.0.683.g7961c838ac-goog\n>\n>\n"},{"id":"493316","messageId":"xmqq1q6xw6hv.fsf@gitster.g","threadId":"61325","inReplyTo":"CAJoAoZmOqEd9HcHMrOUwSXNJi2a8DLeO_11gW1h_HuaK79WEVg@mail.gmail.com","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-04-22T19:18:52Z","receivedAt":"2024-04-22T19:19:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Emily Shaffer <nasamuffin@google.com> writes:\n\n> Thanks for writing this. I, for one, would love to see the process\n> evolve a little to account for the scale of work coming through the\n> list on any given day. However, that's a discussion that will be\n> easier to have once we have the status quo written and checked in.\n> ...\n> So, if nobody disagrees with the content of this document, I think we\n> should absolutely merge it. It will be great for newbies to see what\n> they're getting into, and for me to send to my boss to explain why my\n> predictions for my team's patches landing are so broad.\n\nIsn't it a bit too late to say \"if nobody disagrees with\", after it\nwas pointed out that the world around here does not work that way\n(yet) about a week ago?\n\nIf we have an agreeable v2 already posted on the list that I missed,\nthen sorry, please disregard the above comment.\n\nI still don't think it captures \"the status quo\", which is what you\nwant this document to be, about \"larger-scale decisions\", as the\nIntroduction of the document says.  Can we have a set of pointers in\nthe document, when it gets rerolled, to an actual example of how we\nmade such a larger-scale decision?  Without such illustration with a\nreal world example, it looks to me that what it describes is what we\nwish the process to be (which is not necessarily I would object to),\nbut labeling it as \"describing the status quo\" is very much\nobjectionable.\n\nThanks.\n"},{"id":"493320","messageId":"ZibSUPezSU3ZV1HA@google.com","threadId":"61325","inReplyTo":"xmqq34rmi28h.fsf@gitster.g","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2024-04-22T21:10:40Z","receivedAt":"2024-04-22T21:10:46Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"On 2024.04.15 17:24, Junio C Hamano wrote:\n> Josh Steadmon <steadmon@google.com> writes:\n> \n> > The Git project currently operates according to informal, unstated norms\n> > when it comes to making bigger-picture decisions (above and beyond\n> > individual patches and patch series). Document these norms so that\n> > newcomers to the project can learn what to expect.\n> \n> It would be a good idea to write things down to help newcomers, but\n> the thing is, that we do not do that kind of design discussion +\n> design review + implementaiton waterfall here very often (a notable\n> exception was the sha256 transition design).  I am afraid that\n> \"according to informal unstated norms\" is an overstatement.  We do\n> not have any \"process\" concrete, nothing more than concensus\n> building among amicable parties.\n> \n> Most of the time, technical decisions are made on individual series\n> and by the time the consensus is reached on the series that it is\n> good, the implementation should be finished, and there is no\n> separate \"implementation\" step.  Newcomers would probably want to\n> become familiar with that part of the decision process before\n> joining the \"big picture\" discussion, I suspect.\n\nYes, as I noted in the doc (but need to emphasize), I'm not intending to\ndescribe day-to-day patch review here. I'm thinking more of larger-scale\ndiscussions such as \"Introducing Rust into the Git project\" [1] or the\nspinoff discussion \"Defining a platform support policy\" [2].\n\n[1] https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/\n[2] https://lore.kernel.org/git/CAJoAoZnHGTFhfR6e6r=GMSfVbSNgLoHF-opaWYLbHppiuzi+Rg@mail.gmail.com/\n\nWhile clearly nothing has been decided on those topics, it seems to me\nat least that they follow a pattern of \"discussion now, consensus\n(hopefully) soon, implementation later\".\n\nOr do you think it's more accurate to say that we rarely/never make\ndecisions without patches? Does that mean it's pointless to start a\ndiscussion without a patch series attached? I'm trying to decide whether\nit's worth editing this doc for V2, or just starting over with a much\nsmaller one instead.\n\n> > One particular blind spot for me is how the Project Leadership Committee\n> > operates, or if that's even relevant to this doc.\n> \n> I think this is the part PLC@SFC is supposed to be of relevance:\n> \n> > +For non-technical decisions such as community norms or processes, it is up to\n> > +the community as a whole to implement and sustain agreed-upon changes.\n> \n> > +Anyone with an interest in the topic is welcome to discuss the matter. It is\n> > +expected that all discussion will adhere to the Code of Conduct rules.\n> \n> It is very much worth mentioning CoC here.\n> \n> > diff --git a/Documentation/Makefile b/Documentation/Makefile\n> > index 3f2383a12c..a04da672c6 100644\n> > --- a/Documentation/Makefile\n> > +++ b/Documentation/Makefile\n> > @@ -103,6 +103,7 @@ SP_ARTICLES += howto/coordinate-embargoed-releases\n> >  API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))\n> >  SP_ARTICLES += $(API_DOCS)\n> >  \n> > +TECH_DOCS += DecisionMaking\n> >  TECH_DOCS += ReviewingGuidelines\n> >  TECH_DOCS += MyFirstContribution\n> >  TECH_DOCS += MyFirstObjectWalk\n> >\n> > base-commit: 436d4e5b14df49870a897f64fe92c0ddc7017e4c\n"},{"id":"493321","messageId":"CAJoAoZmR37h5XLa4NnJ+5iZfLNJVfzBgRs4bvaJN4sa=UDtxNw@mail.gmail.com","threadId":"61325","inReplyTo":"xmqq1q6xw6hv.fsf@gitster.g","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Emily Shaffer","fromEmail":"nasamuffin@google.com","sentAt":"2024-04-22T21:12:10Z","receivedAt":"2024-04-22T21:12:24Z","isPatch":true,"sender":{"key":"nasamuffin@google.com","avatar":"https://avatars.githubusercontent.com/u/1606826?v=4"},"body":"On Mon, Apr 22, 2024 at 12:18 PM Junio C Hamano <gitster@pobox.com> wrote:\n>\n> Emily Shaffer <nasamuffin@google.com> writes:\n>\n> > Thanks for writing this. I, for one, would love to see the process\n> > evolve a little to account for the scale of work coming through the\n> > list on any given day. However, that's a discussion that will be\n> > easier to have once we have the status quo written and checked in.\n> > ...\n> > So, if nobody disagrees with the content of this document, I think we\n> > should absolutely merge it. It will be great for newbies to see what\n> > they're getting into, and for me to send to my boss to explain why my\n> > predictions for my team's patches landing are so broad.\n>\n> Isn't it a bit too late to say \"if nobody disagrees with\", after it\n> was pointed out that the world around here does not work that way\n> (yet) about a week ago?\n\nWell, so far we heard from one person who perceives it as status quo\n(the author), one person new to the project, the maintainer, and me :)\nI think Josh is working on a v2 with links as you asked.\n\nI have certainly followed the process Josh described here for a couple\nof large projects coming from my team - to mind, config-based hooks,\nsubmodules UX proposal, and libification proposal all came with\ndiscussion before any patches. I'd love to hear from others who have\nbeen implementing large-scale changes in a different way, like brian,\nor Taylor and the other GitHub folks, too - if this patch is too\ndifferent from what actually happens with their work, let's trim until\nit isn't, instead.\n\n>\n> If we have an agreeable v2 already posted on the list that I missed,\n> then sorry, please disregard the above comment.\n>\n> I still don't think it captures \"the status quo\", which is what you\n> want this document to be, about \"larger-scale decisions\", as the\n> Introduction of the document says.  Can we have a set of pointers in\n> the document, when it gets rerolled, to an actual example of how we\n> made such a larger-scale decision?  Without such illustration with a\n> real world example, it looks to me that what it describes is what we\n> wish the process to be (which is not necessarily I would object to),\n> but labeling it as \"describing the status quo\" is very much\n> objectionable.\n>\n> Thanks.\n"},{"id":"493322","messageId":"xmqqy195t794.fsf@gitster.g","threadId":"61325","inReplyTo":"ZibSUPezSU3ZV1HA@google.com","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-04-22T21:30:47Z","receivedAt":"2024-04-22T21:30:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Josh Steadmon <steadmon@google.com> writes:\n\n> While clearly nothing has been decided on those topics, it seems to me\n> at least that they follow a pattern of \"discussion now, consensus\n> (hopefully) soon, implementation later\".\n>\n> Or do you think it's more accurate to say that we rarely/never make\n> decisions without patches?\n\nAs I said, I do think it is rare for us to start with only \"ideas\"\nwithout anything concrete to comment on, and that is why I asked\nsome references (e.g., URLs into the archive) to a discussion in the\npast of a larger decisions where (1) something is proposed, (2)\ndiscussed, and (3) declaration that a consensus has reached, if a\ndocument describes the status quo.\n\n> Does that mean it's pointless to start a\n> discussion without a patch series attached?\n\nIt does not necessarily mean it is not worth trying to do it more\noften that we have done it rarely.  \n\nIs it desirable to make more larger decisions to implement changes\nthat take longer effort and deeper commitments?  As long as we can\nhave a meaningful discussion, the \"anything concrete to comment on\"\nI mentioned earlier in the previous paragraph does not have to be a\npatch series.\n\n> I'm trying to decide whether it's worth editing this doc for V2,\n> or just starting over with a much smaller one instead.\n\nAnd if the lack of documented process is a factor that contributes\nto the rarity of such decisions, it is a reasonable goal to have a\ndocumented process.  And learning from past sucesses (and failures)\nby starting a document that describes the status quo is a good idea.\n"},{"id":"493337","messageId":"xmqqedawsx3q.fsf@gitster.g","threadId":"61325","inReplyTo":"CAJoAoZmOqEd9HcHMrOUwSXNJi2a8DLeO_11gW1h_HuaK79WEVg@mail.gmail.com","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-04-23T01:10:01Z","receivedAt":"2024-04-23T01:10:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Emily Shaffer <nasamuffin@google.com> writes:\n\n>> +Finalizing a Decision\n>> +---------------------\n>> +After a suitable period of time has passed, the maintainer will judge whether or\n>> +not consensus has been reached. If so, the consensus decision will be\n>> +implemented. Otherwise, discussion may continue, or the proposal may be\n>> +abandoned.\n>\n> I think this captures the status quo. But I'm also left saying,\n> \"indefinitely?! how do we tell people 'thanks, but no thanks'?\"\n\nWouldn't telling people \"Thanks, but no thanks\" count as a\nconsensus, which happens once a consensus to discard the proposal\nhas reached?\n\n\n"},{"id":"493378","messageId":"xmqqjzkn66sw.fsf@gitster.g","threadId":"61325","inReplyTo":"xmqqy195t794.fsf@gitster.g","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-04-23T22:41:19Z","receivedAt":"2024-04-23T22:41:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> As I said, I do think it is rare for us to start with only \"ideas\"\n> without anything concrete to comment on, and that is why I asked\n> some references (e.g., URLs into the archive) to a discussion in the\n> past of a larger decisions where (1) something is proposed, (2)\n> discussed, and (3) declaration that a consensus has reached, if a\n> document describes the status quo.\n\nFYI, what I readily recall was the discussion that started here.\n\n  https://lore.kernel.org/git/20170304011251.GA26789@aiede.mtv.corp.google.com/\n\nIt did have a few iterations and then near the end the consensus has\nturned into a \"patch\" that adds the design document to our history,\nbut otherwise, it did not involve a \"series\" level patch reviews.\n\nHTH..\n"},{"id":"494004","messageId":"xmqqseyzar96.fsf@gitster.g","threadId":"61325","inReplyTo":"xmqqr0f47wp9.fsf@gitster.g","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-03T14:45:25Z","receivedAt":"2024-05-03T14:45:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Enrico Mrass <emrass@google.com> writes:\n>\n>> I'd be curious to learn about norms or practices applied when no consensus\n>> could be reached. It seems worth elaborating on that as part of documenting the\n>> decision-making process.\n>\n> I may be forgetting things, but I do not know if there is a concrete\n> \"here is a norm that we have been using to reach a consensus, not\n> just written down but it has been there\" in the first place, let\n> alone \"here is what we do to resolve an irreconcilable differences\".\n>\n> \"We discuss and try to reach a consensus in an amicable way,\n> sticking to CoC, etc.\" has mostly been good enough for our happy\n> family, perhaps?\n>\n>> ... However, nothing\n>> in the current description strikes me as specific to these larger-scale\n>> decisions.\n>\n> I agree with that.\n\nWe didn't hear any more comments on this topic, but writing down how\nthe world works around here, with the goal to eventually have a set\nof project governance rules, is valuable. Otherwise loud people may\nact according to their own (unwritten) rules that annoy others and\nharm the community.\n\nThanks.\n"},{"id":"494011","messageId":"CANq=j3u5ZHYbJQjhwtnq05GocOE_AVrHodjPOqVCNN7OZHwVsQ@mail.gmail.com","threadId":"61325","inReplyTo":"xmqqseyzar96.fsf@gitster.g","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2024-05-03T15:48:19Z","receivedAt":"2024-05-03T15:48:33Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"Yes, sorry for silence on this thread. I am working on a V2 but\nprobably won't have it ready today.\n\nOn Fri, May 3, 2024 at 7:45 AM Junio C Hamano <gitster@pobox.com> wrote:\n>\n> Junio C Hamano <gitster@pobox.com> writes:\n>\n> > Enrico Mrass <emrass@google.com> writes:\n> >\n> >> I'd be curious to learn about norms or practices applied when no consensus\n> >> could be reached. It seems worth elaborating on that as part of documenting the\n> >> decision-making process.\n> >\n> > I may be forgetting things, but I do not know if there is a concrete\n> > \"here is a norm that we have been using to reach a consensus, not\n> > just written down but it has been there\" in the first place, let\n> > alone \"here is what we do to resolve an irreconcilable differences\".\n> >\n> > \"We discuss and try to reach a consensus in an amicable way,\n> > sticking to CoC, etc.\" has mostly been good enough for our happy\n> > family, perhaps?\n> >\n> >> ... However, nothing\n> >> in the current description strikes me as specific to these larger-scale\n> >> decisions.\n> >\n> > I agree with that.\n>\n> We didn't hear any more comments on this topic, but writing down how\n> the world works around here, with the goal to eventually have a set\n> of project governance rules, is valuable. Otherwise loud people may\n> act according to their own (unwritten) rules that annoy others and\n> harm the community.\n>\n> Thanks.\n"},{"id":"494037","messageId":"xmqqfruy7oq8.fsf@gitster.g","threadId":"61325","inReplyTo":"CANq=j3u5ZHYbJQjhwtnq05GocOE_AVrHodjPOqVCNN7OZHwVsQ@mail.gmail.com","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-03T18:08:15Z","receivedAt":"2024-05-03T18:08:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Josh Steadmon <steadmon@google.com> writes:\n\n> On Fri, May 3, 2024 at 7:45 AM Junio C Hamano <gitster@pobox.com> wrote:\n>>\n>> We didn't hear any more comments on this topic, but writing down how\n>> the world works around here, with the goal to eventually have a set\n>> of project governance rules, is valuable. Otherwise loud people may\n>> act according to their own (unwritten) rules that annoy others and\n>> harm the community.\n\n[jc: do not top post].\n\n> Yes, sorry for silence on this thread. I am working on a V2 but\n> probably won't have it ready today.\n\nDon't be sorry; the message was not addressed to you, but for wider\ncommunity participants---especially the ones with more \"clout\" (or\n\"long timers\" or whatever word we would use to describe those whose\nopinions are trusted by others and count more) need to buy in if we\nwere to first agree on that it is good to have a set of written\nrules, and to then agree on what rules to adopt.\n\nWe might want to pick ideas from https://fossgovernance.org/ for\nexample.\n\n"},{"id":"494051","messageId":"ZjU7CWdwb+xKubul@nand.local","threadId":"61325","inReplyTo":"xmqqfruy7oq8.fsf@gitster.g","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-05-03T19:29:13Z","receivedAt":"2024-05-03T19:29:15Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Fri, May 03, 2024 at 11:08:15AM -0700, Junio C Hamano wrote:\n> > Yes, sorry for silence on this thread. I am working on a V2 but\n> > probably won't have it ready today.\n>\n> Don't be sorry; the message was not addressed to you, but for wider\n> community participants---especially the ones with more \"clout\" (or\n> \"long timers\" or whatever word we would use to describe those whose\n> opinions are trusted by others and count more) need to buy in if we\n> were to first agree on that it is good to have a set of written\n> rules, and to then agree on what rules to adopt.\n\nI have been meaning to respond to this thread since I was mentioned in\nit by Emily, but have been unsure of what to say.\n\nOn one hand, I think the document basically outlines the status-quo of\ndecision making for issues that are larger than the scope of a single\npatch series (think \"should we use Rust?\", \"what is our platform\nsupport policy?\", or \"how should we approach libification?\" not \"is this\nparticular patch (series) correct?\").\n\nSo in that sense, I think that the document is a good starting point,\nand I think that it reasonably captures the status quo.\n\nBut I wish that we didn't have to have such a document in the first\nplace. In my opinion, I would much rather see decisions like \"what is\nour platform policy?\" made according to discussions on a patch that\ndefines what that policy is. That way such decisions can be treated in\nthe same way as ordinary review is today, and we can avoid the need for\na separate process.\n\n(For what it's worth, I thought that the SHA-256 transition was a good\nexample of this. The RFC was posted, and the discussion was had on the\npatch series itself).\n\nAnother way of thinking about this is that I would be extremely\nreluctant to see a similar document proposed for reviewing at the patch\nseries level. In my opinion, the system of reviewers and participants\ndiscussing the series and the maintainer solely determining whether or\nnot consensus has been reached is a good one, and I would be extremely\nhesitant to recommend changing it.\n\nAnd I would advocate for a similar approach to decisions that have\nimplications beyond a single patch series.\n\nThanks,\nTaylor\n"},{"id":"494119","messageId":"ZjiCz4_2KABLshLx@tanuki","threadId":"61325","inReplyTo":"ZjU7CWdwb+xKubul@nand.local","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-06T07:12:15Z","receivedAt":"2024-05-06T07:12:22Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Fri, May 03, 2024 at 03:29:13PM -0400, Taylor Blau wrote:\n> On Fri, May 03, 2024 at 11:08:15AM -0700, Junio C Hamano wrote:\n> > > Yes, sorry for silence on this thread. I am working on a V2 but\n> > > probably won't have it ready today.\n> >\n> > Don't be sorry; the message was not addressed to you, but for wider\n> > community participants---especially the ones with more \"clout\" (or\n> > \"long timers\" or whatever word we would use to describe those whose\n> > opinions are trusted by others and count more) need to buy in if we\n> > were to first agree on that it is good to have a set of written\n> > rules, and to then agree on what rules to adopt.\n\nFair enough. Given that I have been contributing quite a bit more\nrecently I'll feel myself addressed here.\n\n> I have been meaning to respond to this thread since I was mentioned in\n> it by Emily, but have been unsure of what to say.\n> \n> On one hand, I think the document basically outlines the status-quo of\n> decision making for issues that are larger than the scope of a single\n> patch series (think \"should we use Rust?\", \"what is our platform\n> support policy?\", or \"how should we approach libification?\" not \"is this\n> particular patch (series) correct?\").\n> \n> So in that sense, I think that the document is a good starting point,\n> and I think that it reasonably captures the status quo.\n> \n> But I wish that we didn't have to have such a document in the first\n> place. In my opinion, I would much rather see decisions like \"what is\n> our platform policy?\" made according to discussions on a patch that\n> defines what that policy is. That way such decisions can be treated in\n> the same way as ordinary review is today, and we can avoid the need for\n> a separate process.\n\nWith \"such a document\", do you refer to the one documenting the process\nto do such changes or the RFC-style document?\n\nIf you mean the former I disagree and think that it would be great to\ndocument reasonable approaches for how to get to an agreement with the\nGit community. It's especially helpful for newcomers to the commuinity,\nand I do get questions around \"How to reach consensus in Git\" all the\ntime at GitLab.\n\nNow the important part to me is that we should retain flexibility and\nallow us to adapt. It should rather be a helpful resource to newcomers\nthan a rigid set of requirements that everyone has to follow, in my\nopinion.\n\nIf it's the latter (no need for an RFC-style document) I somewhat agree.\nI'm of the opinion that patches are the best way to trigger a more\ninformed discussion because participants will know how something will\nend up looking like. I also tend to send patch series for controversial\ntopics upstream without prior discussion, but my intent here is never to\nforce the result, but rather to force the discussion itself. This of\ncourse comes with the big downside that you may end up wasting quite a\nlot of your own time in case the community disagrees with your approach,\nbut that's acceptable to me most of the time.\n\nIt's only part of the story though. There are bigger changes that simply\ndon't make a ton of sense to propose in the above form, mostly because\ntheir sheer scope is much larger. As you point out further down, things\nlike the SHA256 transition are in that realm.\n\nHere I very much think that having a central place where such large\nprojects are tracked. Given that we have no issue tracker, I think the\nnext-best place to do this would be the Git repository itself. We\nalready do this for some larger topics, but I feel like the bar is quite\nhigh right now. It doesn't make a ton of sense for example to have a\nhuge RFC for the removal of `the_repository`.\n\nSo something that I'd really love to see is if we adopted the micro\nprojects document [1] into Git itself and generalized it such that we\ncan add smallish sections for new large-scale projects. Ideally, such\nprojects could also have trailers that indicate who is interested in\nthose projects such that folks knew whom to reach out to if they want to\nstart contributing to the project. This would help us to document\nconsensus around new projects, and would help newcomers of the\ncommunity to pick up new projects.\n\nPatrick\n\n[1]: https://git.github.io/SoC-2024-Microprojects/\n\n> (For what it's worth, I thought that the SHA-256 transition was a good\n> example of this. The RFC was posted, and the discussion was had on the\n> patch series itself).\n> \n> Another way of thinking about this is that I would be extremely\n> reluctant to see a similar document proposed for reviewing at the patch\n> series level. In my opinion, the system of reviewers and participants\n> discussing the series and the maintainer solely determining whether or\n> not consensus has been reached is a good one, and I would be extremely\n> hesitant to recommend changing it.\n> \n> And I would advocate for a similar approach to decisions that have\n> implications beyond a single patch series.\n> \n> Thanks,\n> Taylor\n> \n"},{"id":"494185","messageId":"mdgbdajenbv23r63hreieemielgdtdkwjzb65pdv3b4rylyyxi@4d3eeymtjvva","threadId":"61325","inReplyTo":"ZjU7CWdwb+xKubul@nand.local","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2024-05-06T19:36:06Z","receivedAt":"2024-05-06T19:36:13Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"On 2024.05.03 15:29, Taylor Blau wrote:\n> On Fri, May 03, 2024 at 11:08:15AM -0700, Junio C Hamano wrote:\n> > > Yes, sorry for silence on this thread. I am working on a V2 but\n> > > probably won't have it ready today.\n> >\n> > Don't be sorry; the message was not addressed to you, but for wider\n> > community participants---especially the ones with more \"clout\" (or\n> > \"long timers\" or whatever word we would use to describe those whose\n> > opinions are trusted by others and count more) need to buy in if we\n> > were to first agree on that it is good to have a set of written\n> > rules, and to then agree on what rules to adopt.\n> \n> I have been meaning to respond to this thread since I was mentioned in\n> it by Emily, but have been unsure of what to say.\n> \n> On one hand, I think the document basically outlines the status-quo of\n> decision making for issues that are larger than the scope of a single\n> patch series (think \"should we use Rust?\", \"what is our platform\n> support policy?\", or \"how should we approach libification?\" not \"is this\n> particular patch (series) correct?\").\n> \n> So in that sense, I think that the document is a good starting point,\n> and I think that it reasonably captures the status quo.\n> \n> But I wish that we didn't have to have such a document in the first\n> place. In my opinion, I would much rather see decisions like \"what is\n> our platform policy?\" made according to discussions on a patch that\n> defines what that policy is. That way such decisions can be treated in\n> the same way as ordinary review is today, and we can avoid the need for\n> a separate process.\n\nHow would you feel about a doc outlining how the process changes as you\ngo from: A) small/medium patch series, to B) larger discussions with\n(parts of) the proposal recorded in patches, to C) large discussions\nwith no patches? This is the structure I'm leaning towards for my V2\ndraft.\n\n\n> (For what it's worth, I thought that the SHA-256 transition was a good\n> example of this. The RFC was posted, and the discussion was had on the\n> patch series itself).\n> \n> Another way of thinking about this is that I would be extremely\n> reluctant to see a similar document proposed for reviewing at the patch\n> series level. In my opinion, the system of reviewers and participants\n> discussing the series and the maintainer solely determining whether or\n> not consensus has been reached is a good one, and I would be extremely\n> hesitant to recommend changing it.\n\nSorry, I'm not sure I understand why you wouldn't want the patch series\nprocess documented? I'm just trying to capture the status quo, not to\npropose or recommend any changes.\n\n\n> And I would advocate for a similar approach to decisions that have\n> implications beyond a single patch series.\n> \n> Thanks,\n> Taylor\n"},{"id":"494199","messageId":"Zjk6LxhEQ75/BsKA@nand.local","threadId":"61325","inReplyTo":"ZjiCz4_2KABLshLx@tanuki","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-05-06T20:14:39Z","receivedAt":"2024-05-06T20:14:41Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Mon, May 06, 2024 at 09:12:15AM +0200, Patrick Steinhardt wrote:\n> On Fri, May 03, 2024 at 03:29:13PM -0400, Taylor Blau wrote:\n> > On Fri, May 03, 2024 at 11:08:15AM -0700, Junio C Hamano wrote:\n> > > > Yes, sorry for silence on this thread. I am working on a V2 but\n> > > > probably won't have it ready today.\n> > >\n> > > Don't be sorry; the message was not addressed to you, but for wider\n> > > community participants---especially the ones with more \"clout\" (or\n> > > \"long timers\" or whatever word we would use to describe those whose\n> > > opinions are trusted by others and count more) need to buy in if we\n> > > were to first agree on that it is good to have a set of written\n> > > rules, and to then agree on what rules to adopt.\n>\n> Fair enough. Given that I have been contributing quite a bit more\n> recently I'll feel myself addressed here.\n>\n> > I have been meaning to respond to this thread since I was mentioned in\n> > it by Emily, but have been unsure of what to say.\n> >\n> > On one hand, I think the document basically outlines the status-quo of\n> > decision making for issues that are larger than the scope of a single\n> > patch series (think \"should we use Rust?\", \"what is our platform\n> > support policy?\", or \"how should we approach libification?\" not \"is this\n> > particular patch (series) correct?\").\n> >\n> > So in that sense, I think that the document is a good starting point,\n> > and I think that it reasonably captures the status quo.\n> >\n> > But I wish that we didn't have to have such a document in the first\n> > place. In my opinion, I would much rather see decisions like \"what is\n> > our platform policy?\" made according to discussions on a patch that\n> > defines what that policy is. That way such decisions can be treated in\n> > the same way as ordinary review is today, and we can avoid the need for\n> > a separate process.\n>\n> With \"such a document\", do you refer to the one documenting the process\n> to do such changes or the RFC-style document?\n\nI did mean the former, but...\n\n> If you mean the former I disagree and think that it would be great to\n> document reasonable approaches for how to get to an agreement with the\n> Git community. It's especially helpful for newcomers to the commuinity,\n> and I do get questions around \"How to reach consensus in Git\" all the\n> time at GitLab.\n\nI think that this framing is more useful. I'd be happy to see us write a\nhelper document intended for new-comers that gives some techniques and\nsuggestions on how to drive discussions forward.\n\nI would be less excited about a document that outlines a rigid process\nfor declaring when consensus has been met, since I think each situation\nis unique, and the large-scale decisions that Josh's document seems to\ntarget are probably not amenable to a one-size-fits-all approach.\n\n> Now the important part to me is that we should retain flexibility and\n> allow us to adapt. It should rather be a helpful resource to newcomers\n> than a rigid set of requirements that everyone has to follow, in my\n> opinion.\n\nYes, definitely.\n\nThanks,\nTaylor\n"},{"id":"494200","messageId":"Zjk6v3Y7zJqtPVVq@nand.local","threadId":"61325","inReplyTo":"mdgbdajenbv23r63hreieemielgdtdkwjzb65pdv3b4rylyyxi@4d3eeymtjvva","subject":"Re: [RFC PATCH] doc: describe the project's decision-making process","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-05-06T20:17:03Z","receivedAt":"2024-05-06T20:17:06Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Mon, May 06, 2024 at 12:36:06PM -0700, Josh Steadmon wrote:\n> How would you feel about a doc outlining how the process changes as you\n> go from: A) small/medium patch series, to B) larger discussions with\n> (parts of) the proposal recorded in patches, to C) large discussions\n> with no patches? This is the structure I'm leaning towards for my V2\n> draft.\n\nThat sounds like a reasonable direction to take.\n\n> > Another way of thinking about this is that I would be extremely\n> > reluctant to see a similar document proposed for reviewing at the patch\n> > series level. In my opinion, the system of reviewers and participants\n> > discussing the series and the maintainer solely determining whether or\n> > not consensus has been reached is a good one, and I would be extremely\n> > hesitant to recommend changing it.\n>\n> Sorry, I'm not sure I understand why you wouldn't want the patch series\n> process documented? I'm just trying to capture the status quo, not to\n> propose or recommend any changes.\n\nApologies, I misspoke here. I don't mean to say that such a document\nshouldn't exist, but rather that I'd be hesitant to see a prescriptive\ndocument outlining how patches are reviewed at too granular a level.\n\nHaving a document like Documentation/ReviewingGuidelines.txt makes sense\nto me and seems like a good thing to keep.\n\nThanks,\nTaylor\n"},{"id":"494338","messageId":"4a829792bf16973799bf3b3db0dd8b49a1ef3815.1715212665.git.steadmon@google.com","threadId":"61325","inReplyTo":"b2ef74c1b0c7482fa880a1519fd6ea1032df7789.1713222673.git.steadmon@google.com","subject":"[PATCH v2] doc: describe the project's decision-making process","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2024-05-09T00:01:30Z","receivedAt":"2024-05-09T00:01:32Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"The Git project currently operates according to an informal\nconsensus-building process, which is not currently well-described.\nDocument what to expect so that we have something concrete to help\ninform newcomers to the project.\n\nThis document explicitly does not aim to impose a formal process to\ndecision-making, nor to change pre-existing norms. Its only aim is to\ndescribe how the project currently operates today.\n\nSigned-off-by: Josh Steadmon <steadmon@google.com>\n---\n\nChanges in V2:\n* Split doc to treat patch series discussion as the general case, with\n  larger discussions (with or without patches) as special situations.\n* Add links to example discussions for certain situations\n* Add link to contributor summit notes\n* Add link to Code of Conduct\n* Add justification for keeping discussion on-list\n* Add paragraph about explicit negative consensus\n* Minor reword of advice on when to CC experts\n* Minor reword of doc intro to avoid indecisive text\n\n Documentation/DecisionMaking.txt | 122 +++++++++++++++++++++++++++++++\n Documentation/Makefile           |   1 +\n 2 files changed, 123 insertions(+)\n create mode 100644 Documentation/DecisionMaking.txt\n\ndiff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt\nnew file mode 100644\nindex 0000000000..55fa3e2185\n--- /dev/null\n+++ b/Documentation/DecisionMaking.txt\n@@ -0,0 +1,122 @@\n+Decision-Making Process in the Git Project\n+==========================================\n+\n+Introduction\n+------------\n+This doc aims to describe the current decision-making process in the Git\n+project. It is a descriptive rather than prescriptive doc; that is, we want to\n+describe how things work in practice rather than explicitly recommending any\n+particular process or changes to the current process.\n+\n+Here we document how the project makes decisions for general patch series, and\n+for larger-scale discussions (with or without patches).\n+\n+\n+General Patch Series\n+--------------------\n+\n+Starting a Discussion\n+~~~~~~~~~~~~~~~~~~~~~\n+For most changes, discussions are started by sending a patch series to the list.\n+There is rarely any need to discuss or ask for approval prior to sending\n+patches; the merit of both the general idea behind your change and the code to\n+implement it will be discussed at the same time.\n+\n+NOTE: For general guides on creating and sending a patch series to the list, see\n+link:SubmittingPatches.html[SubmittingPatches] and\n+link:MyFirstContribution.html[MyFirstContribution]. The remainder of this\n+doc will focus more on what to expect from the list discussion.\n+\n+Because members of the Git community have a wide variety of experience,\n+backgrounds, and values, series are expected to include as much context as\n+possible.\n+\n+If the proposer is aware of individuals with an interest in the subject of the\n+change, it is helpful to CC them on the proposal to increase the likelihood of\n+receiving constructive feedback.\n+\n+Engaging in Discussion\n+~~~~~~~~~~~~~~~~~~~~~~\n+Once a proposal has been made, the community will discuss it on-list. While the\n+maintainer will often participate in discussions, it is not the maintainer's\n+responsibility to guide discussion; the proposer and any other interested\n+parties are expected to stay engaged in the discussion and ensure progress is\n+made.\n+\n+Anyone with an interest in the topic is welcome to discuss the matter. It is\n+expected that all discussion will adhere to the link:../CODE_OF_CONDUCT.md[Code\n+of Conduct] rules.\n+\n+Finalizing a Decision\n+~~~~~~~~~~~~~~~~~~~~~\n+If the maintainer judges that positive consensus has been reached on a topic,\n+they will merge the series, usually to the 'next' integration branch. After a\n+suitable period of time for testing by the community, changes are merged from\n+'next' into 'master', from which official releases are tagged.\n+\n+If consensus has not been reached, discussion may continue, or the proposal may\n+be abandoned if no one continues discussion. More rarely, explicit negative\n+consensus may be reached if the community feels that the series is not suitable,\n+in which case the series should be dropped and discussion ended.\n+\n+There are no strict guidelines used to judge when consensus has been reached,\n+but generally we expect all points of feedback to have been addressed with\n+either a fix or an explanation on why no change is necessary.\n+\n+\n+Larger Discussions (with patches)\n+---------------------------------\n+As with discussions on a general patch series, starting a larger-scale\n+discussion often begins by sending a patch or series to the list. This might\n+take the form of an initial design doc, with implementation following in later\n+iterations of the series (for example,\n+link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding\n+unit tests] or\n+link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based\n+hooks]), or it might include a full implementation from the beginning. In either\n+case, discussion progresses as described above until consensus is reached or the\n+topic is dropped.\n+\n+\n+Larger Discussions (without patches)\n+------------------------------------\n+Occasionally, larger discussions might occur without an associated patch series.\n+These might be very large-scale technical decisions that are beyond the scope of\n+even a single large patch series, or they might be more open-ended,\n+policy-oriented discussions (examples:\n+link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust]\n+or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving\n+submodule UX]). In either case, discussion progresses as described above for\n+general patch series.\n+\n+For larger discussions without a patch series or other concrete implementation,\n+it may be hard to judge when consensus has been reached, as there are not any\n+official guidelines. If discussion stalls at this point, it may be helpful to\n+restart discussion with an RFC patch series or other specific implementation\n+that can be more easily debated.\n+\n+If consensus around a decision has been reached but no implementation provided,\n+it is not the maintainer's responsibility to implement any particular decision.\n+For decisions that require code changes, it is often the case that the original\n+proposer will follow up with a patch series, although it is also common for\n+other interested parties to provide an implementation (or parts of the\n+implementation, for very large changes).\n+\n+For non-technical decisions such as community norms or processes, it is up to\n+the community as a whole to implement and sustain agreed-upon changes.\n+\n+\n+Other Discussion Venues\n+-----------------------\n+Occasionally decision proposals are presented off-list, e.g. at the semi-regular\n+Contributors' Summit. While higher-bandwidth face-to-face discussion is often\n+useful for quickly reaching consensus among attendees, generally we expect to\n+summarize the discussion in notes that can later be presented on-list. For an\n+example, see the thread\n+link:https://lore.kernel.org/git/AC2EB721-2979-43FD-922D-C5076A57F24B@jramsay.com.au/[Notes\n+from Git Contributor Summit, Los Angeles (April 5, 2020)] by James Ramsay.\n+\n+We prefer that \"official\" discussion happens on the list so that the full\n+community has opportunity to engage in discussion. This also means that the\n+mailing list archives contain a more-or-less complete history of project\n+discussions and decisions.\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3f2383a12c..a04da672c6 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -103,6 +103,7 @@ SP_ARTICLES += howto/coordinate-embargoed-releases\n API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))\n SP_ARTICLES += $(API_DOCS)\n \n+TECH_DOCS += DecisionMaking\n TECH_DOCS += ReviewingGuidelines\n TECH_DOCS += MyFirstContribution\n TECH_DOCS += MyFirstObjectWalk\n\nbase-commit: 436d4e5b14df49870a897f64fe92c0ddc7017e4c\n-- \n2.45.0.rc1.225.g2a3ae87e7f-goog\n\n"},{"id":"494373","messageId":"xmqq34qqua9d.fsf@gitster.g","threadId":"61325","inReplyTo":"4a829792bf16973799bf3b3db0dd8b49a1ef3815.1715212665.git.steadmon@google.com","subject":"Re: [PATCH v2] doc: describe the project's decision-making process","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-09T18:10:22Z","receivedAt":"2024-05-09T18:10:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Josh Steadmon <steadmon@google.com> writes:\n\n> diff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt\n> new file mode 100644\n> index 0000000000..55fa3e2185\n> --- /dev/null\n> +++ b/Documentation/DecisionMaking.txt\n> @@ -0,0 +1,122 @@\n> +Decision-Making Process in the Git Project\n> +==========================================\n> +\n> +Introduction\n> +------------\n> +This doc aims to describe the current decision-making process in the Git\n\nIt might not be yet ready to claim this, but when it gets ready to\ndo so, we would want to say \"aims to describe\" -> \"describes\".\n\n> +General Patch Series\n> +--------------------\n\nAs if there is a separate section for \"Special Patch Series\"?  But\nmore seriously, I cannot quite shake this feeling that most of these\nare covered in the beginning of the SubmittingPatches document.\nThere probably are small things that are missing over there that can\nbe found here, but given the large overlap, I have a feeling that\nthese additions are better done over there, not here, and limit the\nscope of this document to decisions beyond the \"General\" patch\nseries.  There already is SubmittingPatches::[[patch-flow]] section\nthat may be a better place for the material we see here.\n\n> +Starting a Discussion\n> +~~~~~~~~~~~~~~~~~~~~~\n> +For most changes, discussions are started by sending a patch series to the list.\n> +There is rarely any need to discuss or ask for approval prior to sending\n> +patches; the merit of both the general idea behind your change and the code to\n> +implement it will be discussed at the same time.\n\nWe do not say \"you need no permission or pre-approval\" which may be\na good thing to add to SubmittingPatches.\n\n> +NOTE: For general guides on creating and sending a patch series to the list, see\n> +link:SubmittingPatches.html[SubmittingPatches] and\n> +link:MyFirstContribution.html[MyFirstContribution]. The remainder of this\n> +doc will focus more on what to expect from the list discussion.\n\nSo my question is if there is anything of substance left we should\nhave here, or if it is better to add them to SubmittingPatches so\nthat readers need to read one fewer documents.\n\n> +Because members of the Git community have a wide variety of experience,\n> +backgrounds, and values, series are expected to include as much context as\n> +possible.\n> +\n> +If the proposer is aware of individuals with an interest in the subject of the\n> +change, it is helpful to CC them on the proposal to increase the likelihood of\n> +receiving constructive feedback.\n\nSubmittingPatches::[[describe-changes]] and [[patch-flow]] might be\na better home for some sentences stolen from here?\n\n> +Engaging in Discussion\n> +~~~~~~~~~~~~~~~~~~~~~~\n> +Once a proposal has been made, the community will discuss it on-list. While the\n> +maintainer will often participate in discussions, it is not the maintainer's\n> +responsibility to guide discussion; the proposer and any other interested\n> +parties are expected to stay engaged in the discussion and ensure progress is\n> +made.\n> +\n> +Anyone with an interest in the topic is welcome to discuss the matter. It is\n> +expected that all discussion will adhere to the link:../CODE_OF_CONDUCT.md[Code\n> +of Conduct] rules.\n\nDitto for the above to SubmittingPatches::[[send-patches]] and [[patch-flow]]?\n\n> +Finalizing a Decision\n> +~~~~~~~~~~~~~~~~~~~~~\n> +If the maintainer judges that positive consensus has been reached on a topic,\n> +they will merge the series, usually to the 'next' integration branch. After a\n> +suitable period of time for testing by the community, changes are merged from\n> +'next' into 'master', from which official releases are tagged.\n> +\n> +If consensus has not been reached, discussion may continue, or the proposal may\n> +be abandoned if no one continues discussion. More rarely, explicit negative\n> +consensus may be reached if the community feels that the series is not suitable,\n> +in which case the series should be dropped and discussion ended.\n> +\n> +There are no strict guidelines used to judge when consensus has been reached,\n> +but generally we expect all points of feedback to have been addressed with\n> +either a fix or an explanation on why no change is necessary.\n\nDitto for the above to SubmittingPatches::[[patch-flow]]?\n\n\n> +Larger Discussions (with patches)\n> +---------------------------------\n> +As with discussions on a general patch series, starting a larger-scale\n> +discussion often begins by sending a patch or series to the list. This might\n> +take the form of an initial design doc, with implementation following in later\n> +iterations of the series (for example,\n> +link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding\n> +unit tests] or\n> +link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based\n> +hooks]), or it might include a full implementation from the beginning. In either\n> +case, discussion progresses as described above until consensus is reached or the\n> +topic is dropped.\n\nOK.\n\n> +Larger Discussions (without patches)\n> +------------------------------------\n> +Occasionally, larger discussions might occur without an associated patch series.\n> +These might be very large-scale technical decisions that are beyond the scope of\n> +even a single large patch series, or they might be more open-ended,\n> +policy-oriented discussions (examples:\n> +link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust]\n> +or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving\n> +submodule UX]). In either case, discussion progresses as described above for\n> +general patch series.\n> +\n> +For larger discussions without a patch series or other concrete implementation,\n> +it may be hard to judge when consensus has been reached, as there are not any\n> +official guidelines. If discussion stalls at this point, it may be helpful to\n> +restart discussion with an RFC patch series or other specific implementation\n> +that can be more easily debated.\n> +\n> +If consensus around a decision has been reached but no implementation provided,\n> +it is not the maintainer's responsibility to implement any particular decision.\n\nAs it is not anybody's responsibility, it may be confusing to single\nthe maintainer out in this sentence.  Saying \"it is not\" alone will\nleave readers wondering \"then whose responsibility is it?\".  \n\nI would say:\n\n    When consensus is reached that it is a good idea, the original\n    proposer is expected to coordinate the effort to make it happen,\n    with help from others who were involved in the discussion as\n    needed.\n\nwithout pretending that the issues that needs consensus are black\nand white \"requiring code changes\" vs \"non-technical\" without any\nother colors.  IOW, I'd drop the following two paragraphs, as the\nabove would be sufficient.\n\n> +For decisions that require code changes, it is often the case that the original\n> +proposer will follow up with a patch series, although it is also common for\n> +other interested parties to provide an implementation (or parts of the\n> +implementation, for very large changes).\n> +\n> +For non-technical decisions such as community norms or processes, it is up to\n> +the community as a whole to implement and sustain agreed-upon changes.\n\n\n> +Other Discussion Venues\n> +-----------------------\n> +Occasionally decision proposals are presented off-list, e.g. at the semi-regular\n> +Contributors' Summit. While higher-bandwidth face-to-face discussion is often\n> +useful for quickly reaching consensus among attendees, generally we expect to\n> +summarize the discussion in notes that can later be presented on-list. For an\n> +example, see the thread\n> +link:https://lore.kernel.org/git/AC2EB721-2979-43FD-922D-C5076A57F24B@jramsay.com.au/[Notes\n> +from Git Contributor Summit, Los Angeles (April 5, 2020)] by James Ramsay.\n> +\n> +We prefer that \"official\" discussion happens on the list so that the full\n> +community has opportunity to engage in discussion. This also means that the\n> +mailing list archives contain a more-or-less complete history of project\n> +discussions and decisions.\n\nOK.\n\nThanks.\n"},{"id":"494376","messageId":"xmqqy18issfv.fsf@gitster.g","threadId":"61325","inReplyTo":"xmqq34qqua9d.fsf@gitster.g","subject":"Re: [PATCH v2] doc: describe the project's decision-making process","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-09T19:20:36Z","receivedAt":"2024-05-09T19:20:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> There probably are small things that are missing over there that can\n> be found here, but given the large overlap, I have a feeling that\n> these additions are better done over there, not here, and limit the\n> scope of this document to decisions beyond the \"General\" patch\n> series.  There already is SubmittingPatches::[[patch-flow]] section\n> that may be a better place for the material we see here.\n\nTo see how well this approach can go, I plan to spend some time\ntoday reorganizing SubmittingPatches and enhancing some descriptions\nin it.  The plan is roughly\n\n * Add a preamble to explain \"why\" you would want to send, and we\n   would want to receive, patches in a larger picture.\n\n * Move [[patch-flow]] section to the very beginning, with a bit of\n   enhanced description on the review cycle, i.e. what patches,\n   their review comments, and review responses are expected to\n   contain and for what goal.\n\n * Possibly remove things from other sections that would become\n   redundant by the enhancement above.\n\n\n   \n"},{"id":"494379","messageId":"20240509211318.641896-1-gitster@pobox.com","threadId":"61325","inReplyTo":"xmqqy18issfv.fsf@gitster.g","subject":"[PATCH 0/2] Describe patch-flow better in SubmittingPatches","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-09T21:13:16Z","receivedAt":"2024-05-09T21:13:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"So here is what I came up with.  The main idea behind this\n\"counter-proposal\" is to make sure we do not add to the pile of\ndocuments a new contributor needs to read before being able to send\n\"a perfect patch\".  Reading SubmittingPatches alone should be\nsufficient for them to understand what to expect and what are\nexpected of them.\n\nJunio C Hamano (2):\n  SubmittingPatches: move the patch-flow section earlier\n  SubmittingPatches: extend the \"flow\" section\n\n Documentation/SubmittingPatches | 126 +++++++++++++++++++-------------\n 1 file changed, 75 insertions(+), 51 deletions(-)\n\n-- \n2.45.0-119-g0f3415f1f8\n\n"},{"id":"494380","messageId":"20240509211318.641896-2-gitster@pobox.com","threadId":"61325","inReplyTo":"20240509211318.641896-1-gitster@pobox.com","subject":"[PATCH 1/2] SubmittingPatches: move the patch-flow section earlier","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-09T21:13:17Z","receivedAt":"2024-05-09T21:13:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Before discussing the small details of how the patch gets sent, we'd\nwant to give people a larger picture first to set the expectation\nstraight.  The existing patch-flow section covers materials that are\nsuitable for that purpose, so move it to the beginning of the\ndocument.  We'll update the contents of the section to clarify what\ngoal the patch submitter is working towards in the next step, which\nwill make it easier to understand the reason behind the individual\nrules presented in latter parts of the document.\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/SubmittingPatches | 98 ++++++++++++++++-----------------\n 1 file changed, 49 insertions(+), 49 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 727992541c..142b82a71b 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -7,6 +7,55 @@ Here are some guidelines for contributing back to this\n project. There is also a link:MyFirstContribution.html[step-by-step tutorial]\n available which covers many of these same guidelines.\n \n+[[patch-flow]]\n+=== An ideal patch flow\n+\n+Here is an ideal patch flow for this project the current maintainer\n+suggests to the contributors:\n+\n+. You come up with an itch.  You code it up.\n+\n+. Send it to the list and cc people who may need to know about\n+  the change.\n++\n+The people who may need to know are the ones whose code you\n+are butchering.  These people happen to be the ones who are\n+most likely to be knowledgeable enough to help you, but\n+they have no obligation to help you (i.e. you ask for help,\n+don't demand).  +git log -p {litdd} _$area_you_are_modifying_+ would\n+help you find out who they are.\n+\n+. You get comments and suggestions for improvements.  You may\n+  even get them in an \"on top of your change\" patch form.\n+\n+. Polish, refine, and re-send to the list and the people who\n+  spend their time to improve your patch.  Go back to step (2).\n+\n+. The list forms consensus that the last round of your patch is\n+  good.  Send it to the maintainer and cc the list.\n+\n+. A topic branch is created with the patch and is merged to `next`,\n+  and cooked further and eventually graduates to `master`.\n+\n+In any time between the (2)-(3) cycle, the maintainer may pick it up\n+from the list and queue it to `seen`, in order to make it easier for\n+people to play with it without having to pick up and apply the patch to\n+their trees themselves.\n+\n+[[patch-status]]\n+=== Know the status of your patch after submission\n+\n+* You can use Git itself to find out when your patch is merged in\n+  master. `git pull --rebase` will automatically skip already-applied\n+  patches, and will let you know. This works only if you rebase on top\n+  of the branch in which your patch has been merged (i.e. it will not\n+  tell you if your patch is merged in `seen` if you rebase on top of\n+  master).\n+\n+* Read the Git mailing list, the maintainer regularly posts messages\n+  entitled \"What's cooking in git.git\" giving\n+  the status of various proposed changes.\n+\n [[choose-starting-point]]\n === Choose a starting point.\n \n@@ -569,55 +618,6 @@ Patches to these parts should be based on their trees.\n \thttps://github.com/jnavila/git-manpages-l10n/\n \n \n-[[patch-flow]]\n-== An ideal patch flow\n-\n-Here is an ideal patch flow for this project the current maintainer\n-suggests to the contributors:\n-\n-. You come up with an itch.  You code it up.\n-\n-. Send it to the list and cc people who may need to know about\n-  the change.\n-+\n-The people who may need to know are the ones whose code you\n-are butchering.  These people happen to be the ones who are\n-most likely to be knowledgeable enough to help you, but\n-they have no obligation to help you (i.e. you ask for help,\n-don't demand).  +git log -p {litdd} _$area_you_are_modifying_+ would\n-help you find out who they are.\n-\n-. You get comments and suggestions for improvements.  You may\n-  even get them in an \"on top of your change\" patch form.\n-\n-. Polish, refine, and re-send to the list and the people who\n-  spend their time to improve your patch.  Go back to step (2).\n-\n-. The list forms consensus that the last round of your patch is\n-  good.  Send it to the maintainer and cc the list.\n-\n-. A topic branch is created with the patch and is merged to `next`,\n-  and cooked further and eventually graduates to `master`.\n-\n-In any time between the (2)-(3) cycle, the maintainer may pick it up\n-from the list and queue it to `seen`, in order to make it easier for\n-people to play with it without having to pick up and apply the patch to\n-their trees themselves.\n-\n-[[patch-status]]\n-== Know the status of your patch after submission\n-\n-* You can use Git itself to find out when your patch is merged in\n-  master. `git pull --rebase` will automatically skip already-applied\n-  patches, and will let you know. This works only if you rebase on top\n-  of the branch in which your patch has been merged (i.e. it will not\n-  tell you if your patch is merged in `seen` if you rebase on top of\n-  master).\n-\n-* Read the Git mailing list, the maintainer regularly posts messages\n-  entitled \"What's cooking in git.git\" giving\n-  the status of various proposed changes.\n-\n == GitHub CI[[GHCI]]\n \n With an account at GitHub, you can use GitHub CI to test your changes\n-- \n2.45.0-119-g0f3415f1f8\n\n"},{"id":"494381","messageId":"20240509211318.641896-3-gitster@pobox.com","threadId":"61325","inReplyTo":"20240509211318.641896-1-gitster@pobox.com","subject":"[PATCH 2/2] SubmittingPatches: extend the \"flow\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-09T21:13:18Z","receivedAt":"2024-05-09T21:13:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Explain a full lifecycle of a patch series upfront, so that it is\nclear when key decisions to \"accept\" a series is made and how a new\npatch series becomes a part of a new release.\n\nEarlier, we described an idealized patch flow that nobody followed\nin practice.  Instead, describe what flow was used in practice for\nthe past decade that worked well for us.\n\nFold the \"you need to monitor the progress of your topic\" section\ninto the primary \"patch lifecycle\" section, as that is one of the\nthings the patch submitter is responsible for.\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/SubmittingPatches | 112 +++++++++++++++++++-------------\n 1 file changed, 68 insertions(+), 44 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 142b82a71b..8922aae4a5 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -8,53 +8,76 @@ project. There is also a link:MyFirstContribution.html[step-by-step tutorial]\n available which covers many of these same guidelines.\n \n [[patch-flow]]\n-=== An ideal patch flow\n-\n-Here is an ideal patch flow for this project the current maintainer\n-suggests to the contributors:\n-\n-. You come up with an itch.  You code it up.\n-\n-. Send it to the list and cc people who may need to know about\n-  the change.\n+=== A not-so ideal patch flow\n+\n+To help us understand the reason behind various guidelines given later\n+in the document, first lets understand how the lifecycle of a typical\n+patch series for this project goes.\n+\n+. You come up with an itch.  You code it up.  You do not need any\n+  pre-authorization from the project to do so.  Your patches will be\n+  reviewed by other contributors on the mailing list, and the reviews\n+  will be done to assess the merit of various things, like the general\n+  idea behind your patch (including \"is it solving a problem worth\n+  solving in the first place?\"), the reason behind the design of the\n+  solution, and the actual implementation.\n+\n+. You send the patches to the list and cc people who may need to know\n+  about the change.  Your goal is *not* necessarily to convince others\n+  that what you are building is a good idea.  Your goal is to get help\n+  in coming up with a solution for the \"itch\" that is better than what\n+  you can build alone.\n +\n-The people who may need to know are the ones whose code you\n-are butchering.  These people happen to be the ones who are\n+The people who may need to know are the ones who worked on the code\n+you are touching.  These people happen to be the ones who are\n most likely to be knowledgeable enough to help you, but\n-they have no obligation to help you (i.e. you ask for help,\n-don't demand).  +git log -p {litdd} _$area_you_are_modifying_+ would\n+they have no obligation to help you (i.e. you ask them for help,\n+you don't demand).  +git log -p {litdd} _$area_you_are_modifying_+ would\n help you find out who they are.\n \n-. You get comments and suggestions for improvements.  You may\n-  even get them in an \"on top of your change\" patch form.\n-\n-. Polish, refine, and re-send to the list and the people who\n-  spend their time to improve your patch.  Go back to step (2).\n-\n-. The list forms consensus that the last round of your patch is\n-  good.  Send it to the maintainer and cc the list.\n-\n-. A topic branch is created with the patch and is merged to `next`,\n-  and cooked further and eventually graduates to `master`.\n-\n-In any time between the (2)-(3) cycle, the maintainer may pick it up\n-from the list and queue it to `seen`, in order to make it easier for\n-people to play with it without having to pick up and apply the patch to\n-their trees themselves.\n-\n-[[patch-status]]\n-=== Know the status of your patch after submission\n-\n-* You can use Git itself to find out when your patch is merged in\n-  master. `git pull --rebase` will automatically skip already-applied\n-  patches, and will let you know. This works only if you rebase on top\n-  of the branch in which your patch has been merged (i.e. it will not\n-  tell you if your patch is merged in `seen` if you rebase on top of\n-  master).\n+. You get comments and suggestions for improvements.  You may even get\n+  them in an \"on top of your change\" patch form.  You are expected to\n+  respond to them with \"Reply-All\" on the mailing list, while taking\n+  them into account while preparing an updated set of patches.\n+\n+. Polish, refine, and re-send your patches to the list and the people who\n+  spent their time to improve your patch.  Go back to step (2).\n+\n+. While the above iterations improve your patches, the maintainer may\n+  pick the patches up from the list and queue them to the `seen`\n+  branch, in order to make it easier for people to play with it\n+  without having to pick up and apply the patches to their trees\n+  themselves.  Being in `seen` has no other meaning.  Specifically, it\n+  does not mean the patch was \"accepted\" in any way.\n+\n+. When the discussion reaches a consensus that the latest iteration of\n+  the patches are in good enough shape, the maintainer includes the\n+  topic in the \"What's cooking\" report that are sent out a few times a\n+  week to the mailing list, marked as \"Will merge to 'next'.\"  This\n+  decision is primarily made by the maintainer with the help from\n+  reviewers.\n+\n+. Once the patches hit 'next', the discussion can still continue to\n+  further improve them by adding more patches on top, but by the time\n+  a topic gets merged to 'next', it is expected that everybody agreed\n+  that the scope and the basic direction of the topic are appropriate,\n+  so such an incremental updates are expected to be limited to small\n+  corrections and polishing.  After a topic cooks for some time (like\n+  7 calendar days) in 'next' without further tweaks on top, it gets\n+  merged to the 'master' branch and wait to become part of the next\n+  major release.\n+\n+Earlier versions of this document outlined a slightly different patch\n+flow in an idealized world, where the original submitter gathered\n+agreements from the participants of the discussion and sent the final\n+\"we all agreed that this is the good version--please apply\" patches\n+to the maintainer.  In practice, this almost never happened.  The flow\n+described above reflects the reality much better and can be considered\n+the \"canonical\" procedure to get the patch accepted to the project.\n+\n+In the following sections, many techniques and conventions are listed\n+to help your patches get reviewed effectively.\n \n-* Read the Git mailing list, the maintainer regularly posts messages\n-  entitled \"What's cooking in git.git\" giving\n-  the status of various proposed changes.\n \n [[choose-starting-point]]\n === Choose a starting point.\n@@ -241,8 +264,9 @@ reasons:\n   which case, they can explain why they extend your code to cover\n   files, too).\n \n-The goal of your log message is to convey the _why_ behind your\n-change to help future developers.\n+The goal of your log message is to convey the _why_ behind your change\n+to help future developers.  The reviewers will also make sure that\n+your proposed log message will serve this purpose well.\n \n The first line of the commit message should be a short description (50\n characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]),\n-- \n2.45.0-119-g0f3415f1f8\n\n"},{"id":"494420","messageId":"CAOLa=ZS_5+x7_xxppD8BE7RA0X+BFHPm=ffWg4JDgORqR5=sqQ@mail.gmail.com","threadId":"61325","inReplyTo":"20240509211318.641896-3-gitster@pobox.com","subject":"Re: [PATCH 2/2] SubmittingPatches: extend the \"flow\" section","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2024-05-10T10:08:59Z","receivedAt":"2024-05-10T10:09:01Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Explain a full lifecycle of a patch series upfront, so that it is\n> clear when key decisions to \"accept\" a series is made and how a new\n> patch series becomes a part of a new release.\n>\n> Earlier, we described an idealized patch flow that nobody followed\n> in practice.  Instead, describe what flow was used in practice for\n> the past decade that worked well for us.\n>\n> Fold the \"you need to monitor the progress of your topic\" section\n> into the primary \"patch lifecycle\" section, as that is one of the\n> things the patch submitter is responsible for.\n>\n> Signed-off-by: Junio C Hamano <gitster@pobox.com>\n> ---\n>  Documentation/SubmittingPatches | 112 +++++++++++++++++++-------------\n>  1 file changed, 68 insertions(+), 44 deletions(-)\n>\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index 142b82a71b..8922aae4a5 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -8,53 +8,76 @@ project. There is also a link:MyFirstContribution.html[step-by-step tutorial]\n>  available which covers many of these same guidelines.\n>\n>  [[patch-flow]]\n> -=== An ideal patch flow\n> -\n> -Here is an ideal patch flow for this project the current maintainer\n> -suggests to the contributors:\n> -\n> -. You come up with an itch.  You code it up.\n> -\n> -. Send it to the list and cc people who may need to know about\n> -  the change.\n> +=== A not-so ideal patch flow\n> +\n> +To help us understand the reason behind various guidelines given later\n> +in the document, first lets understand how the lifecycle of a typical\n> +patch series for this project goes.\n> +\n> +. You come up with an itch.  You code it up.  You do not need any\n> +  pre-authorization from the project to do so.  Your patches will be\n\nWouldn't it be better to have the following sentences after the next\npara?\n\nSo the flow would be\n- Have an itch. Code it up.\n- Send patches to list.\n- Get reviews.\n\n> +  reviewed by other contributors on the mailing list, and the reviews\n> +  will be done to assess the merit of various things, like the general\n> +  idea behind your patch (including \"is it solving a problem worth\n> +  solving in the first place?\"), the reason behind the design of the\n> +  solution, and the actual implementation.\n> +\n> +. You send the patches to the list and cc people who may need to know\n> +  about the change.  Your goal is *not* necessarily to convince others\n> +  that what you are building is a good idea.  Your goal is to get help\n> +  in coming up with a solution for the \"itch\" that is better than what\n> +  you can build alone.\n>  +\n> -The people who may need to know are the ones whose code you\n> -are butchering.  These people happen to be the ones who are\n> +The people who may need to know are the ones who worked on the code\n> +you are touching.  These people happen to be the ones who are\n\nThis reads much _nicer_.\n\n>  most likely to be knowledgeable enough to help you, but\n> -they have no obligation to help you (i.e. you ask for help,\n> -don't demand).  +git log -p {litdd} _$area_you_are_modifying_+ would\n> +they have no obligation to help you (i.e. you ask them for help,\n> +you don't demand).  +git log -p {litdd} _$area_you_are_modifying_+ would\n>  help you find out who they are.\n>\n> -. You get comments and suggestions for improvements.  You may\n> -  even get them in an \"on top of your change\" patch form.\n> -\n> -. Polish, refine, and re-send to the list and the people who\n> -  spend their time to improve your patch.  Go back to step (2).\n> -\n> -. The list forms consensus that the last round of your patch is\n> -  good.  Send it to the maintainer and cc the list.\n> -\n> -. A topic branch is created with the patch and is merged to `next`,\n> -  and cooked further and eventually graduates to `master`.\n> -\n> -In any time between the (2)-(3) cycle, the maintainer may pick it up\n> -from the list and queue it to `seen`, in order to make it easier for\n> -people to play with it without having to pick up and apply the patch to\n> -their trees themselves.\n> -\n> -[[patch-status]]\n> -=== Know the status of your patch after submission\n> -\n> -* You can use Git itself to find out when your patch is merged in\n> -  master. `git pull --rebase` will automatically skip already-applied\n> -  patches, and will let you know. This works only if you rebase on top\n> -  of the branch in which your patch has been merged (i.e. it will not\n> -  tell you if your patch is merged in `seen` if you rebase on top of\n> -  master).\n> +. You get comments and suggestions for improvements.  You may even get\n> +  them in an \"on top of your change\" patch form.  You are expected to\n> +  respond to them with \"Reply-All\" on the mailing list, while taking\n> +  them into account while preparing an updated set of patches.\n> +\n> +. Polish, refine, and re-send your patches to the list and the people who\n> +  spent their time to improve your patch.  Go back to step (2).\n> +\n> +. While the above iterations improve your patches, the maintainer may\n> +  pick the patches up from the list and queue them to the `seen`\n> +  branch, in order to make it easier for people to play with it\n> +  without having to pick up and apply the patches to their trees\n> +  themselves.  Being in `seen` has no other meaning.  Specifically, it\n> +  does not mean the patch was \"accepted\" in any way.\n> +\n> +. When the discussion reaches a consensus that the latest iteration of\n> +  the patches are in good enough shape, the maintainer includes the\n> +  topic in the \"What's cooking\" report that are sent out a few times a\n> +  week to the mailing list, marked as \"Will merge to 'next'.\"  This\n> +  decision is primarily made by the maintainer with the help from\n> +  reviewers.\n> +\n> +. Once the patches hit 'next', the discussion can still continue to\n> +  further improve them by adding more patches on top, but by the time\n> +  a topic gets merged to 'next', it is expected that everybody agreed\n> +  that the scope and the basic direction of the topic are appropriate,\n> +  so such an incremental updates are expected to be limited to small\n> +  corrections and polishing.  After a topic cooks for some time (like\n> +  7 calendar days) in 'next' without further tweaks on top, it gets\n> +  merged to the 'master' branch and wait to become part of the next\n> +  major release.\n> +\n> +Earlier versions of this document outlined a slightly different patch\n> +flow in an idealized world, where the original submitter gathered\n> +agreements from the participants of the discussion and sent the final\n> +\"we all agreed that this is the good version--please apply\" patches\n> +to the maintainer.  In practice, this almost never happened.  The flow\n> +described above reflects the reality much better and can be considered\n> +the \"canonical\" procedure to get the patch accepted to the project.\n> +\n> +In the following sections, many techniques and conventions are listed\n> +to help your patches get reviewed effectively.\n>\n> -* Read the Git mailing list, the maintainer regularly posts messages\n> -  entitled \"What's cooking in git.git\" giving\n> -  the status of various proposed changes.\n>\n>  [[choose-starting-point]]\n>  === Choose a starting point.\n> @@ -241,8 +264,9 @@ reasons:\n>    which case, they can explain why they extend your code to cover\n>    files, too).\n>\n> -The goal of your log message is to convey the _why_ behind your\n> -change to help future developers.\n> +The goal of your log message is to convey the _why_ behind your change\n> +to help future developers.  The reviewers will also make sure that\n> +your proposed log message will serve this purpose well.\n>\n>  The first line of the commit message should be a short description (50\n>  characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]),\n> --\n> 2.45.0-119-g0f3415f1f8\n\nThanks, this is great improvement.\n"},{"id":"494471","messageId":"xmqqh6f564kp.fsf@gitster.g","threadId":"61325","inReplyTo":"CAOLa=ZS_5+x7_xxppD8BE7RA0X+BFHPm=ffWg4JDgORqR5=sqQ@mail.gmail.com","subject":"Re: [PATCH 2/2] SubmittingPatches: extend the \"flow\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-10T15:59:18Z","receivedAt":"2024-05-10T15:59:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Karthik Nayak <karthik.188@gmail.com> writes:\n\n>> +=== A not-so ideal patch flow\n>> +\n>> +To help us understand the reason behind various guidelines given later\n>> +in the document, first lets understand how the lifecycle of a typical\n>> +patch series for this project goes.\n>> +\n>> +. You come up with an itch.  You code it up.  You do not need any\n>> +  pre-authorization from the project to do so.  Your patches will be\n>\n> Wouldn't it be better to have the following sentences after the next\n> para?\n>\n> So the flow would be\n> - Have an itch. Code it up.\n> - Send patches to list.\n> - Get reviews.\n\nI am not sure what exactly you are suggesting.  \"The next para\"\nmeaning?  The sentence far below that begins with \"In the following\nsections, many techniques and ...\"?\n\nAlso, \"Get reviews\" is not a single step that is an end of story, so\nwhat you wrote is a bit misleading as a short summary.\n\nThe goal of this update is to reduce duplicates by describing a\ntypical life-cycle of a patch series from the inception of an idea\nto the decision to include it in the next release here, so the\nproposed \"decision making\" document can focus on issues at a level\nlarger than a topic of a patch series, and a contributor, especially\na new one who wants to give us their first patch series, can learn\nby only reading these paragraphs how the world works around here\nwith their patch series from the beginning to the end.  So what\nhappens after \"Get reviews.\" is a part of the same \"flow\".  Namely\nthese three paragraphs---the original submitter cannot just leave\nwith \"now it is their problem\" after they get reviews.  They are now\nintegral part of the discussion and we expect to see them see the\nprocess through.\n\n>> +. While the above iterations improve your patches, the maintainer may\n>> +  pick the patches up from the list and queue them to the `seen`\n>> +  branch, in order to make it easier for people to play with it\n>> +  without having to pick up and apply the patches to their trees\n>> +  themselves.  Being in `seen` has no other meaning.  Specifically, it\n>> +  does not mean the patch was \"accepted\" in any way.\n>> +\n>> +. When the discussion reaches a consensus that the latest iteration of\n>> +  the patches are in good enough shape, the maintainer includes the\n>> +  topic in the \"What's cooking\" report that are sent out a few times a\n>> +  week to the mailing list, marked as \"Will merge to 'next'.\"  This\n>> +  decision is primarily made by the maintainer with the help from\n>> +  reviewers.\n>> +\n>> +. Once the patches hit 'next', the discussion can still continue to\n>> +  further improve them by adding more patches on top, but by the time\n>> +  a topic gets merged to 'next', it is expected that everybody agreed\n>> +  that the scope and the basic direction of the topic are appropriate,\n>> +  so such an incremental updates are expected to be limited to small\n>> +  corrections and polishing.  After a topic cooks for some time (like\n>> +  7 calendar days) in 'next' without further tweaks on top, it gets\n>> +  merged to the 'master' branch and wait to become part of the next\n>> +  major release.\n\n>> +Earlier versions of this document outlined a slightly different patch\n>> +flow in an idealized world, where the original submitter gathered\n>> +agreements from the participants of the discussion and sent the final\n>> +\"we all agreed that this is the good version--please apply\" patches\n>> +to the maintainer.  In practice, this almost never happened.  The flow\n>> +described above reflects the reality much better and can be considered\n>> +the \"canonical\" procedure to get the patch accepted to the project.\n\nI actually was expecting to hear more comments about this paragraph,\nwhich makes a lame excuse for naming the section \"A not-so ideal\".\nAfter sleeping on it, I think it belongs to the log message of this\nchange, not here.  Future wanna-be developers do not have to know\nwhat process we wanted to have---they benefit from reading what the\nprocess _is_ in practice in a more direct way.\n\n>> +In the following sections, many techniques and conventions are listed\n>> +to help your patches get reviewed effectively.\n\nThanks.\n"},{"id":"494476","messageId":"20240510165526.1412338-1-gitster@pobox.com","threadId":"61325","inReplyTo":"xmqqy18issfv.fsf@gitster.g","subject":"[PATCH v2 0/2] Describe life cycle of a patch series","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-10T16:55:24Z","receivedAt":"2024-05-10T16:55:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Start the SubmittingPatches document by describing the life cycle of\na typical patch series to give the readers a sense of what process\nto expect, including how the key events like rerolls, merge to 'next',\nand graduation to 'master' happen, and what are expected of them.\n\nRelative to the initial version, \n\n . [Patch 1/2] explains in its proposed log message that there is no\n   content changes except for the section level adjustment\n\n . [Patch 2/2] has lost a paragraph about how the process is\n   different from the \"ideal\", which is irrelevant to the target\n   audience who want to learn what the current practice is.\n\nI'll follow these patches up with a separate patch to clarify the\nproposed \"decision making\" document by making it more focused on\ndeciding on issues at levels higher than an individual patch series,\nwhich is fully covered by the SubmittingPatches document.\n\nJunio C Hamano (2):\n  SubmittingPatches: move the patch-flow section earlier\n  SubmittingPatches: extend the \"flow\" section\n\n Documentation/SubmittingPatches | 121 ++++++++++++++++++--------------\n 1 file changed, 70 insertions(+), 51 deletions(-)\n\n-- \n2.45.0-119-g0f3415f1f8\n\n"},{"id":"494477","messageId":"20240510165526.1412338-2-gitster@pobox.com","threadId":"61325","inReplyTo":"20240510165526.1412338-1-gitster@pobox.com","subject":"[PATCH v2 1/2] SubmittingPatches: move the patch-flow section earlier","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-10T16:55:25Z","receivedAt":"2024-05-10T16:55:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Before discussing the small details of how the patch gets sent, we'd\nwant to give people a larger picture first to set the expectation\nstraight.  The existing patch-flow section covers materials that are\nsuitable for that purpose, so move it to the beginning of the\ndocument.  We'll update the contents of the section to clarify what\ngoal the patch submitter is working towards in the next step, which\nwill make it easier to understand the reason behind the individual\nrules presented in latter parts of the document.\n\nThis step only moves two sections (patch-flow and patch-status)\nwithout changing their contents, except that their section levels\nare demoted from Level 1 to Level 2 to fit better in the document\nstructure at their new place.\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/SubmittingPatches | 98 ++++++++++++++++-----------------\n 1 file changed, 49 insertions(+), 49 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 384893be1c..e82c119dfa 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -7,6 +7,55 @@ Here are some guidelines for contributing back to this\n project. There is also a link:MyFirstContribution.html[step-by-step tutorial]\n available which covers many of these same guidelines.\n \n+[[patch-flow]]\n+=== An ideal patch flow\n+\n+Here is an ideal patch flow for this project the current maintainer\n+suggests to the contributors:\n+\n+. You come up with an itch.  You code it up.\n+\n+. Send it to the list and cc people who may need to know about\n+  the change.\n++\n+The people who may need to know are the ones whose code you\n+are butchering.  These people happen to be the ones who are\n+most likely to be knowledgeable enough to help you, but\n+they have no obligation to help you (i.e. you ask for help,\n+don't demand).  +git log -p {litdd} _$area_you_are_modifying_+ would\n+help you find out who they are.\n+\n+. You get comments and suggestions for improvements.  You may\n+  even get them in an \"on top of your change\" patch form.\n+\n+. Polish, refine, and re-send to the list and the people who\n+  spend their time to improve your patch.  Go back to step (2).\n+\n+. The list forms consensus that the last round of your patch is\n+  good.  Send it to the maintainer and cc the list.\n+\n+. A topic branch is created with the patch and is merged to `next`,\n+  and cooked further and eventually graduates to `master`.\n+\n+In any time between the (2)-(3) cycle, the maintainer may pick it up\n+from the list and queue it to `seen`, in order to make it easier for\n+people to play with it without having to pick up and apply the patch to\n+their trees themselves.\n+\n+[[patch-status]]\n+=== Know the status of your patch after submission\n+\n+* You can use Git itself to find out when your patch is merged in\n+  master. `git pull --rebase` will automatically skip already-applied\n+  patches, and will let you know. This works only if you rebase on top\n+  of the branch in which your patch has been merged (i.e. it will not\n+  tell you if your patch is merged in `seen` if you rebase on top of\n+  master).\n+\n+* Read the Git mailing list, the maintainer regularly posts messages\n+  entitled \"What's cooking in git.git\" giving\n+  the status of various proposed changes.\n+\n [[choose-starting-point]]\n === Choose a starting point.\n \n@@ -562,55 +611,6 @@ repositories.\n \n Patches to these parts should be based on their trees.\n \n-[[patch-flow]]\n-== An ideal patch flow\n-\n-Here is an ideal patch flow for this project the current maintainer\n-suggests to the contributors:\n-\n-. You come up with an itch.  You code it up.\n-\n-. Send it to the list and cc people who may need to know about\n-  the change.\n-+\n-The people who may need to know are the ones whose code you\n-are butchering.  These people happen to be the ones who are\n-most likely to be knowledgeable enough to help you, but\n-they have no obligation to help you (i.e. you ask for help,\n-don't demand).  +git log -p {litdd} _$area_you_are_modifying_+ would\n-help you find out who they are.\n-\n-. You get comments and suggestions for improvements.  You may\n-  even get them in an \"on top of your change\" patch form.\n-\n-. Polish, refine, and re-send to the list and the people who\n-  spend their time to improve your patch.  Go back to step (2).\n-\n-. The list forms consensus that the last round of your patch is\n-  good.  Send it to the maintainer and cc the list.\n-\n-. A topic branch is created with the patch and is merged to `next`,\n-  and cooked further and eventually graduates to `master`.\n-\n-In any time between the (2)-(3) cycle, the maintainer may pick it up\n-from the list and queue it to `seen`, in order to make it easier for\n-people to play with it without having to pick up and apply the patch to\n-their trees themselves.\n-\n-[[patch-status]]\n-== Know the status of your patch after submission\n-\n-* You can use Git itself to find out when your patch is merged in\n-  master. `git pull --rebase` will automatically skip already-applied\n-  patches, and will let you know. This works only if you rebase on top\n-  of the branch in which your patch has been merged (i.e. it will not\n-  tell you if your patch is merged in `seen` if you rebase on top of\n-  master).\n-\n-* Read the Git mailing list, the maintainer regularly posts messages\n-  entitled \"What's cooking in git.git\" giving\n-  the status of various proposed changes.\n-\n == GitHub CI[[GHCI]]\n \n With an account at GitHub, you can use GitHub CI to test your changes\n-- \n2.45.0-119-g0f3415f1f8\n\n"},{"id":"494478","messageId":"20240510165526.1412338-3-gitster@pobox.com","threadId":"61325","inReplyTo":"20240510165526.1412338-1-gitster@pobox.com","subject":"[PATCH v2 2/2] SubmittingPatches: extend the \"flow\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-10T16:55:26Z","receivedAt":"2024-05-10T16:55:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Explain a full lifecycle of a patch series upfront, so that it is\nclear when key decisions to \"accept\" a series is made and how a new\npatch series becomes a part of a new release.\n\nFold the \"you need to monitor the progress of your topic\" section\ninto the primary \"patch lifecycle\" section, as that is one of the\nthings the patch submitter is responsible for.  It is not like \"I\nsent a patch and responded to review messages, and now it is their\nproblem\".  They need to see their patch through the patch life\ncycle.\n\nEarlier versions of this document outlined a slightly different\npatch flow in an idealized world, where the original submitter\ngathered agreements from the participants of the discussion and sent\nthe final \"we all agreed that this is the good version--please\napply\" patches to the maintainer.  In practice, this almost never\nhappened.  Instead, describe what flow was used in practice for the\npast decade that worked well for us.\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/SubmittingPatches | 103 +++++++++++++++++++-------------\n 1 file changed, 61 insertions(+), 42 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex e82c119dfa..8332073e27 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -8,53 +8,71 @@ project. There is also a link:MyFirstContribution.html[step-by-step tutorial]\n available which covers many of these same guidelines.\n \n [[patch-flow]]\n-=== An ideal patch flow\n+=== A typical life cycle of a patch series\n \n-Here is an ideal patch flow for this project the current maintainer\n-suggests to the contributors:\n+To help us understand the reason behind various guidelines given later\n+in the document, first let's understand how the life cycle of a\n+typical patch series for this project goes.\n \n-. You come up with an itch.  You code it up.\n-\n-. Send it to the list and cc people who may need to know about\n-  the change.\n+. You come up with an itch.  You code it up.  You do not need any\n+  pre-authorization from the project to do so.\n++\n+Your patches will be reviewed by other contributors on the mailing\n+list, and the reviews will be done to assess the merit of various\n+things, like the general idea behind your patch (including \"is it\n+solving a problem worth solving in the first place?\"), the reason\n+behind the design of the solution, and the actual implementation.\n+The guidelines given here are there to help your patches by making\n+them easier to understand by the reviewers.\n+\n+. You send the patches to the list and cc people who may need to know\n+  about the change.  Your goal is *not* necessarily to convince others\n+  that what you are building is good.  Your goal is to get help in\n+  coming up with a solution for the \"itch\" that is better than what\n+  you can build alone.\n +\n-The people who may need to know are the ones whose code you\n-are butchering.  These people happen to be the ones who are\n+The people who may need to know are the ones who worked on the code\n+you are touching.  These people happen to be the ones who are\n most likely to be knowledgeable enough to help you, but\n-they have no obligation to help you (i.e. you ask for help,\n-don't demand).  +git log -p {litdd} _$area_you_are_modifying_+ would\n+they have no obligation to help you (i.e. you ask them for help,\n+you don't demand).  +git log -p {litdd} _$area_you_are_modifying_+ would\n help you find out who they are.\n \n-. You get comments and suggestions for improvements.  You may\n-  even get them in an \"on top of your change\" patch form.\n-\n-. Polish, refine, and re-send to the list and the people who\n-  spend their time to improve your patch.  Go back to step (2).\n-\n-. The list forms consensus that the last round of your patch is\n-  good.  Send it to the maintainer and cc the list.\n-\n-. A topic branch is created with the patch and is merged to `next`,\n-  and cooked further and eventually graduates to `master`.\n-\n-In any time between the (2)-(3) cycle, the maintainer may pick it up\n-from the list and queue it to `seen`, in order to make it easier for\n-people to play with it without having to pick up and apply the patch to\n-their trees themselves.\n-\n-[[patch-status]]\n-=== Know the status of your patch after submission\n-\n-* You can use Git itself to find out when your patch is merged in\n-  master. `git pull --rebase` will automatically skip already-applied\n-  patches, and will let you know. This works only if you rebase on top\n-  of the branch in which your patch has been merged (i.e. it will not\n-  tell you if your patch is merged in `seen` if you rebase on top of\n-  master).\n+. You get comments and suggestions for improvements.  You may even get\n+  them in an \"on top of your change\" patch form.  You are expected to\n+  respond to them with \"Reply-All\" on the mailing list, while taking\n+  them into account while preparing an updated set of patches.\n+\n+. Polish, refine, and re-send your patches to the list and to the people\n+  who spent their time to improve your patch.  Go back to step (2).\n+\n+. While the above iterations improve your patches, the maintainer may\n+  pick the patches up from the list and queue them to the `seen`\n+  branch, in order to make it easier for people to play with it\n+  without having to pick up and apply the patches to their trees\n+  themselves.  Being in `seen` has no other meaning.  Specifically, it\n+  does not mean the patch was \"accepted\" in any way.\n+\n+. When the discussion reaches a consensus that the latest iteration of\n+  the patches are in good enough shape, the maintainer includes the\n+  topic in the \"What's cooking\" report that are sent out a few times a\n+  week to the mailing list, marked as \"Will merge to 'next'.\"  This\n+  decision is primarily made by the maintainer with help from those\n+  who participated in the review discussion.\n+\n+. After the patches are merged to the 'next' branch, the discussion\n+  can still continue to further improve them by adding more patches on\n+  top, but by the time a topic gets merged to 'next', it is expected\n+  that everybody agrees that the scope and the basic direction of the\n+  topic are appropriate, so such an incremental updates are limited to\n+  small corrections and polishing.  After a topic cooks for some time\n+  (like 7 calendar days) in 'next' without needing further tweaks on\n+  top, it gets merged to the 'master' branch and wait to become part\n+  of the next major release.\n+\n+In the following sections, many techniques and conventions are listed\n+to help your patches get reviewed effectively in such a life cycle.\n \n-* Read the Git mailing list, the maintainer regularly posts messages\n-  entitled \"What's cooking in git.git\" giving\n-  the status of various proposed changes.\n \n [[choose-starting-point]]\n === Choose a starting point.\n@@ -241,8 +259,9 @@ reasons:\n   which case, they can explain why they extend your code to cover\n   files, too).\n \n-The goal of your log message is to convey the _why_ behind your\n-change to help future developers.\n+The goal of your log message is to convey the _why_ behind your change\n+to help future developers.  The reviewers will also make sure that\n+your proposed log message will serve this purpose well.\n \n The first line of the commit message should be a short description (50\n characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]),\n-- \n2.45.0-119-g0f3415f1f8\n\n"},{"id":"494479","messageId":"20240510165617.1412642-1-gitster@pobox.com","threadId":"61325","inReplyTo":"20240510165526.1412338-1-gitster@pobox.com","subject":"[PATCH] decisions: focus on larger scale issues","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-10T16:56:17Z","receivedAt":"2024-05-10T16:56:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Remove \"General Patch Series\" section, as its contents should be\nfully covered by the SubmittingPatches document, and make this new\ndocument primarily about decisions at a larger scale.  Adjust a few\nsentences that used to refer to an earlier description on patch\ndiscussion to refer to the SubmittingPatches document instead.\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/DecisionMaking.txt | 86 +++++++-------------------------\n 1 file changed, 19 insertions(+), 67 deletions(-)\n\ndiff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt\nindex 55fa3e2185..274ddfa62c 100644\n--- a/Documentation/DecisionMaking.txt\n+++ b/Documentation/DecisionMaking.txt\n@@ -3,79 +3,27 @@ Decision-Making Process in the Git Project\n \n Introduction\n ------------\n-This doc aims to describe the current decision-making process in the Git\n+This document describes the current decision-making process in the Git\n project. It is a descriptive rather than prescriptive doc; that is, we want to\n describe how things work in practice rather than explicitly recommending any\n particular process or changes to the current process.\n \n-Here we document how the project makes decisions for general patch series, and\n-for larger-scale discussions (with or without patches).\n-\n-\n-General Patch Series\n---------------------\n-\n-Starting a Discussion\n-~~~~~~~~~~~~~~~~~~~~~\n-For most changes, discussions are started by sending a patch series to the list.\n-There is rarely any need to discuss or ask for approval prior to sending\n-patches; the merit of both the general idea behind your change and the code to\n-implement it will be discussed at the same time.\n-\n-NOTE: For general guides on creating and sending a patch series to the list, see\n-link:SubmittingPatches.html[SubmittingPatches] and\n-link:MyFirstContribution.html[MyFirstContribution]. The remainder of this\n-doc will focus more on what to expect from the list discussion.\n-\n-Because members of the Git community have a wide variety of experience,\n-backgrounds, and values, series are expected to include as much context as\n-possible.\n-\n-If the proposer is aware of individuals with an interest in the subject of the\n-change, it is helpful to CC them on the proposal to increase the likelihood of\n-receiving constructive feedback.\n-\n-Engaging in Discussion\n-~~~~~~~~~~~~~~~~~~~~~~\n-Once a proposal has been made, the community will discuss it on-list. While the\n-maintainer will often participate in discussions, it is not the maintainer's\n-responsibility to guide discussion; the proposer and any other interested\n-parties are expected to stay engaged in the discussion and ensure progress is\n-made.\n-\n-Anyone with an interest in the topic is welcome to discuss the matter. It is\n-expected that all discussion will adhere to the link:../CODE_OF_CONDUCT.md[Code\n-of Conduct] rules.\n-\n-Finalizing a Decision\n-~~~~~~~~~~~~~~~~~~~~~\n-If the maintainer judges that positive consensus has been reached on a topic,\n-they will merge the series, usually to the 'next' integration branch. After a\n-suitable period of time for testing by the community, changes are merged from\n-'next' into 'master', from which official releases are tagged.\n-\n-If consensus has not been reached, discussion may continue, or the proposal may\n-be abandoned if no one continues discussion. More rarely, explicit negative\n-consensus may be reached if the community feels that the series is not suitable,\n-in which case the series should be dropped and discussion ended.\n-\n-There are no strict guidelines used to judge when consensus has been reached,\n-but generally we expect all points of feedback to have been addressed with\n-either a fix or an explanation on why no change is necessary.\n+Here we document how the project makes decisions for discussions\n+(with or without patches), in scale larger than an individual patch\n+series (which is fully covered by the SubmittingPatches document).\n \n \n Larger Discussions (with patches)\n ---------------------------------\n-As with discussions on a general patch series, starting a larger-scale\n+As with discussions on an individual patch series, starting a larger-scale\n discussion often begins by sending a patch or series to the list. This might\n take the form of an initial design doc, with implementation following in later\n iterations of the series (for example,\n-link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding\n-unit tests] or\n-link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based\n-hooks]), or it might include a full implementation from the beginning. In either\n-case, discussion progresses as described above until consensus is reached or the\n-topic is dropped.\n+link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding unit tests] or\n+link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based hooks]),\n+or it might include a full implementation from the beginning.\n+In either case, discussion progresses the same way for an individual patch series,\n+until consensus is reached or the topic is dropped.\n \n \n Larger Discussions (without patches)\n@@ -85,9 +33,8 @@ These might be very large-scale technical decisions that are beyond the scope of\n even a single large patch series, or they might be more open-ended,\n policy-oriented discussions (examples:\n link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust]\n-or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving\n-submodule UX]). In either case, discussion progresses as described above for\n-general patch series.\n+or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving submodule UX]).\n+In either case, discussion progresses as described above for general patch series.\n \n For larger discussions without a patch series or other concrete implementation,\n it may be hard to judge when consensus has been reached, as there are not any\n@@ -95,8 +42,11 @@ official guidelines. If discussion stalls at this point, it may be helpful to\n restart discussion with an RFC patch series or other specific implementation\n that can be more easily debated.\n \n-If consensus around a decision has been reached but no implementation provided,\n-it is not the maintainer's responsibility to implement any particular decision.\n+When consensus is reached that it is a good idea, the original\n+proposer is expected to coordinate the effort to make it happen,\n+with help from others who were involved in the discussion, as\n+needed.\n+\n For decisions that require code changes, it is often the case that the original\n proposer will follow up with a patch series, although it is also common for\n other interested parties to provide an implementation (or parts of the\n@@ -104,6 +54,8 @@ implementation, for very large changes).\n \n For non-technical decisions such as community norms or processes, it is up to\n the community as a whole to implement and sustain agreed-upon changes.\n+The project leadership committe (PLC) may help the implementation of\n+policy decisions.\n \n \n Other Discussion Venues\n-- \n2.45.0-119-g0f3415f1f8\n\n"},{"id":"494490","messageId":"CAOLa=ZRQGFPVD04n_3r5VjHjkxF4bWrW6Po7DyRVfeO9v08TXA@mail.gmail.com","threadId":"61325","inReplyTo":"xmqqh6f564kp.fsf@gitster.g","subject":"Re: [PATCH 2/2] SubmittingPatches: extend the \"flow\" section","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2024-05-10T19:09:05Z","receivedAt":"2024-05-10T19:09:07Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Karthik Nayak <karthik.188@gmail.com> writes:\n>\n>>> +=== A not-so ideal patch flow\n>>> +\n>>> +To help us understand the reason behind various guidelines given later\n>>> +in the document, first lets understand how the lifecycle of a typical\n>>> +patch series for this project goes.\n>>> +\n>>> +. You come up with an itch.  You code it up.  You do not need any\n>>> +  pre-authorization from the project to do so.  Your patches will be\n>>\n>> Wouldn't it be better to have the following sentences after the next\n>> para?\n>>\n>> So the flow would be\n>> - Have an itch. Code it up.\n>> - Send patches to list.\n>> - Get reviews.\n>\n> I am not sure what exactly you are suggesting.  \"The next para\"\n> meaning?  The sentence far below that begins with \"In the following\n> sections, many techniques and ...\"?\n>\n\nLet me be more verbose, I was suggesting to change it to:\n\n+. You come up with an itch.  You code it up.  You do not need any\n+  pre-authorization from the project to do so.\n+\n+. You send the patches to the list and cc people who may need to know\n+  about the change.  Your goal is *not* necessarily to convince others\n+  that what you are building is a good idea.  Your goal is to get help\n+  in coming up with a solution for the \"itch\" that is better than what\n+  you can build alone.\n+\n+. Your patches will be reviewed by other contributors on the mailing\n+  list, and the reviews will be done to assess the merit of various\n+  things, like the general idea behind your patch (including \"is it\n+  solving a problem worth solving in the first place?\"), the reason\n+  behind the design of the solution, and the actual implementation.\n\n\n> Also, \"Get reviews\" is not a single step that is an end of story, so\n> what you wrote is a bit misleading as a short summary.\n>\n\nI was trying to be brief, my intention was to capture the whole block\nwhich, I agree wasn't the best shortening.\n\n> The goal of this update is to reduce duplicates by describing a\n> typical life-cycle of a patch series from the inception of an idea\n> to the decision to include it in the next release here, so the\n> proposed \"decision making\" document can focus on issues at a level\n> larger than a topic of a patch series, and a contributor, especially\n> a new one who wants to give us their first patch series, can learn\n> by only reading these paragraphs how the world works around here\n> with their patch series from the beginning to the end.  So what\n> happens after \"Get reviews.\" is a part of the same \"flow\".  Namely\n> these three paragraphs---the original submitter cannot just leave\n> with \"now it is their problem\" after they get reviews.  They are now\n> integral part of the discussion and we expect to see them see the\n> process through.\n\nI see what you're trying to say, my comment was on the fact that it\nseemed like there was jumps between the timeline of events and seemed\nconfusing, with my suggestion we still hold the same points and just\nreshuffle the order a little to ensure that the flow of events is a\nlittle easier to understand.\n\n\n\n>>> +. While the above iterations improve your patches, the maintainer may\n>>> +  pick the patches up from the list and queue them to the `seen`\n>>> +  branch, in order to make it easier for people to play with it\n>>> +  without having to pick up and apply the patches to their trees\n>>> +  themselves.  Being in `seen` has no other meaning.  Specifically, it\n>>> +  does not mean the patch was \"accepted\" in any way.\n>>> +\n>>> +. When the discussion reaches a consensus that the latest iteration of\n>>> +  the patches are in good enough shape, the maintainer includes the\n>>> +  topic in the \"What's cooking\" report that are sent out a few times a\n>>> +  week to the mailing list, marked as \"Will merge to 'next'.\"  This\n>>> +  decision is primarily made by the maintainer with the help from\n>>> +  reviewers.\n>>> +\n>>> +. Once the patches hit 'next', the discussion can still continue to\n>>> +  further improve them by adding more patches on top, but by the time\n>>> +  a topic gets merged to 'next', it is expected that everybody agreed\n>>> +  that the scope and the basic direction of the topic are appropriate,\n>>> +  so such an incremental updates are expected to be limited to small\n>>> +  corrections and polishing.  After a topic cooks for some time (like\n>>> +  7 calendar days) in 'next' without further tweaks on top, it gets\n>>> +  merged to the 'master' branch and wait to become part of the next\n>>> +  major release.\n>\n\nI wasn't referring to the above three paragraphs and I agree with the\npoints laid down here, I also happened to have missed reading and\nresponding to your mail on my series [1], around how to iterate your\npatches and check for and resolve conflicts with other ongoing topics.\n\nI think that would be a great value add to these points. I will smoothen\nit and send it to the list soon.\n\n>>> +Earlier versions of this document outlined a slightly different patch\n>>> +flow in an idealized world, where the original submitter gathered\n>>> +agreements from the participants of the discussion and sent the final\n>>> +\"we all agreed that this is the good version--please apply\" patches\n>>> +to the maintainer.  In practice, this almost never happened.  The flow\n>>> +described above reflects the reality much better and can be considered\n>>> +the \"canonical\" procedure to get the patch accepted to the project.\n>\n> I actually was expecting to hear more comments about this paragraph,\n> which makes a lame excuse for naming the section \"A not-so ideal\".\n> After sleeping on it, I think it belongs to the log message of this\n> change, not here.  Future wanna-be developers do not have to know\n> what process we wanted to have---they benefit from reading what the\n> process _is_ in practice in a more direct way.\n>\n>>> +In the following sections, many techniques and conventions are listed\n>>> +to help your patches get reviewed effectively.\n>\n> Thanks.\n\nThanks\n\n[1]: https://lore.kernel.org/git/xmqqy18lpoqg.fsf@gitster.g/\n"},{"id":"494839","messageId":"ohvjmfopwq74ndsvnkzzw7h4i3zoxvf5iwevokfxjeza5wbq2f@q4olaeuvmya2","threadId":"61325","inReplyTo":"20240510165526.1412338-1-gitster@pobox.com","subject":"Re: [PATCH v2 0/2] Describe life cycle of a patch series","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2024-05-15T20:35:56Z","receivedAt":"2024-05-15T20:36:03Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"On 2024.05.10 09:55, Junio C Hamano wrote:\n> Start the SubmittingPatches document by describing the life cycle of\n> a typical patch series to give the readers a sense of what process\n> to expect, including how the key events like rerolls, merge to 'next',\n> and graduation to 'master' happen, and what are expected of them.\n> \n> Relative to the initial version, \n> \n>  . [Patch 1/2] explains in its proposed log message that there is no\n>    content changes except for the section level adjustment\n> \n>  . [Patch 2/2] has lost a paragraph about how the process is\n>    different from the \"ideal\", which is irrelevant to the target\n>    audience who want to learn what the current practice is.\n> \n> I'll follow these patches up with a separate patch to clarify the\n> proposed \"decision making\" document by making it more focused on\n> deciding on issues at levels higher than an individual patch series,\n> which is fully covered by the SubmittingPatches document.\n> \n> Junio C Hamano (2):\n>   SubmittingPatches: move the patch-flow section earlier\n>   SubmittingPatches: extend the \"flow\" section\n> \n>  Documentation/SubmittingPatches | 121 ++++++++++++++++++--------------\n>  1 file changed, 70 insertions(+), 51 deletions(-)\n> \n> -- \n> 2.45.0-119-g0f3415f1f8\n> \n\nThis version looks good to me.\n"},{"id":"494840","messageId":"absdyh7wwpmzw67yrqa7c6ph4czekl2t2ro24muhk4k5pmqysk@b757bukiowtl","threadId":"61325","inReplyTo":"20240510165617.1412642-1-gitster@pobox.com","subject":"Re: [PATCH] decisions: focus on larger scale issues","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2024-05-15T20:36:42Z","receivedAt":"2024-05-15T20:36:48Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"On 2024.05.10 09:56, Junio C Hamano wrote:\n> Remove \"General Patch Series\" section, as its contents should be\n> fully covered by the SubmittingPatches document, and make this new\n> document primarily about decisions at a larger scale.  Adjust a few\n> sentences that used to refer to an earlier description on patch\n> discussion to refer to the SubmittingPatches document instead.\n> \n> Signed-off-by: Junio C Hamano <gitster@pobox.com>\n> ---\n>  Documentation/DecisionMaking.txt | 86 +++++++-------------------------\n>  1 file changed, 19 insertions(+), 67 deletions(-)\n\nLooks good to me. I'll squash this in to the next version I send out.\n"},{"id":"494843","messageId":"xmqqh6eyvlyy.fsf@gitster.g","threadId":"61325","inReplyTo":"absdyh7wwpmzw67yrqa7c6ph4czekl2t2ro24muhk4k5pmqysk@b757bukiowtl","subject":"Re: [PATCH] decisions: focus on larger scale issues","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-15T20:50:13Z","receivedAt":"2024-05-15T20:50:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Josh Steadmon <steadmon@google.com> writes:\n\n> On 2024.05.10 09:56, Junio C Hamano wrote:\n>> Remove \"General Patch Series\" section, as its contents should be\n>> fully covered by the SubmittingPatches document, and make this new\n>> document primarily about decisions at a larger scale.  Adjust a few\n>> sentences that used to refer to an earlier description on patch\n>> discussion to refer to the SubmittingPatches document instead.\n>> \n>> Signed-off-by: Junio C Hamano <gitster@pobox.com>\n>> ---\n>>  Documentation/DecisionMaking.txt | 86 +++++++-------------------------\n>>  1 file changed, 19 insertions(+), 67 deletions(-)\n>\n> Looks good to me. I'll squash this in to the next version I send out.\n\nThanks.\n"},{"id":"494914","messageId":"5446ca49e042b104923ac2004d845a5f9018c9d9.1715894135.git.steadmon@google.com","threadId":"61325","inReplyTo":"b2ef74c1b0c7482fa880a1519fd6ea1032df7789.1713222673.git.steadmon@google.com","subject":"[PATCH v3] doc: describe the project's decision-making process","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2024-05-16T21:20:53Z","receivedAt":"2024-05-16T21:20:56Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"The Git project currently operates according to an informal\nconsensus-building process, which is currently described in the\nSubmittingPatches document. However, that focuses on small/medium-scale\npatch series. For larger-scale decisions, the process is not as well\ndescribed. Document what to expect so that we have something concrete to\nhelp inform newcomers to the project.\n\nThis document explicitly does not aim to impose a formal process to\ndecision-making, nor to change pre-existing norms. Its only aim is to\ndescribe how the project currently operates today.\n\nCo-authored-by: Junio C Hamano <gitster@pobox.com>\nSigned-off-by: Josh Steadmon <steadmon@google.com>\n---\ndoc: describe the project's decision-making process\n\nChanges in V3:\n* Squash in Junio's suggested patch to remove discussion of small-scale\n  patch series.\n\nChanges in V2:\n* Split doc to treat patch series discussion as the general case, with\n  larger discussions (with or without patches) as special situations.\n* Add links to example discussions for certain situations\n* Add link to contributor summit notes\n* Add link to Code of Conduct doc\n* Add justification for keeping discussion on-list\n* Add paragraph about explicit negative consensus\n* Minor reword of advice on when to CC experts\n* MInor reword of doc intro to avoid indecisive text\n\nRange-diff against v2:\n1:  4a829792bf ! 1:  5446ca49e0 doc: describe the project's decision-making process\n    @@ Commit message\n         doc: describe the project's decision-making process\n     \n         The Git project currently operates according to an informal\n    -    consensus-building process, which is not currently well-described.\n    -    Document what to expect so that we have something concrete to help\n    -    inform newcomers to the project.\n    +    consensus-building process, which is currently described in the\n    +    SubmittingPatches document. However, that focuses on small/medium-scale\n    +    patch series. For larger-scale decisions, the process is not as well\n    +    described. Document what to expect so that we have something concrete to\n    +    help inform newcomers to the project.\n     \n         This document explicitly does not aim to impose a formal process to\n         decision-making, nor to change pre-existing norms. Its only aim is to\n         describe how the project currently operates today.\n     \n    +    Co-authored-by: Junio C Hamano <gitster@pobox.com>\n     \n      ## Documentation/DecisionMaking.txt (new) ##\n     @@\n    @@ Documentation/DecisionMaking.txt (new)\n     +\n     +Introduction\n     +------------\n    -+This doc aims to describe the current decision-making process in the Git\n    ++This document describes the current decision-making process in the Git\n     +project. It is a descriptive rather than prescriptive doc; that is, we want to\n     +describe how things work in practice rather than explicitly recommending any\n     +particular process or changes to the current process.\n     +\n    -+Here we document how the project makes decisions for general patch series, and\n    -+for larger-scale discussions (with or without patches).\n    -+\n    -+\n    -+General Patch Series\n    -+--------------------\n    -+\n    -+Starting a Discussion\n    -+~~~~~~~~~~~~~~~~~~~~~\n    -+For most changes, discussions are started by sending a patch series to the list.\n    -+There is rarely any need to discuss or ask for approval prior to sending\n    -+patches; the merit of both the general idea behind your change and the code to\n    -+implement it will be discussed at the same time.\n    -+\n    -+NOTE: For general guides on creating and sending a patch series to the list, see\n    -+link:SubmittingPatches.html[SubmittingPatches] and\n    -+link:MyFirstContribution.html[MyFirstContribution]. The remainder of this\n    -+doc will focus more on what to expect from the list discussion.\n    -+\n    -+Because members of the Git community have a wide variety of experience,\n    -+backgrounds, and values, series are expected to include as much context as\n    -+possible.\n    -+\n    -+If the proposer is aware of individuals with an interest in the subject of the\n    -+change, it is helpful to CC them on the proposal to increase the likelihood of\n    -+receiving constructive feedback.\n    -+\n    -+Engaging in Discussion\n    -+~~~~~~~~~~~~~~~~~~~~~~\n    -+Once a proposal has been made, the community will discuss it on-list. While the\n    -+maintainer will often participate in discussions, it is not the maintainer's\n    -+responsibility to guide discussion; the proposer and any other interested\n    -+parties are expected to stay engaged in the discussion and ensure progress is\n    -+made.\n    -+\n    -+Anyone with an interest in the topic is welcome to discuss the matter. It is\n    -+expected that all discussion will adhere to the link:../CODE_OF_CONDUCT.md[Code\n    -+of Conduct] rules.\n    -+\n    -+Finalizing a Decision\n    -+~~~~~~~~~~~~~~~~~~~~~\n    -+If the maintainer judges that positive consensus has been reached on a topic,\n    -+they will merge the series, usually to the 'next' integration branch. After a\n    -+suitable period of time for testing by the community, changes are merged from\n    -+'next' into 'master', from which official releases are tagged.\n    -+\n    -+If consensus has not been reached, discussion may continue, or the proposal may\n    -+be abandoned if no one continues discussion. More rarely, explicit negative\n    -+consensus may be reached if the community feels that the series is not suitable,\n    -+in which case the series should be dropped and discussion ended.\n    -+\n    -+There are no strict guidelines used to judge when consensus has been reached,\n    -+but generally we expect all points of feedback to have been addressed with\n    -+either a fix or an explanation on why no change is necessary.\n    ++Here we document how the project makes decisions for discussions\n    ++(with or without patches), in scale larger than an individual patch\n    ++series (which is fully covered by the SubmittingPatches document).\n     +\n     +\n     +Larger Discussions (with patches)\n     +---------------------------------\n    -+As with discussions on a general patch series, starting a larger-scale\n    ++As with discussions on an individual patch series, starting a larger-scale\n     +discussion often begins by sending a patch or series to the list. This might\n     +take the form of an initial design doc, with implementation following in later\n     +iterations of the series (for example,\n    -+link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding\n    -+unit tests] or\n    -+link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based\n    -+hooks]), or it might include a full implementation from the beginning. In either\n    -+case, discussion progresses as described above until consensus is reached or the\n    -+topic is dropped.\n    ++link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding unit tests] or\n    ++link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based hooks]),\n    ++or it might include a full implementation from the beginning.\n    ++In either case, discussion progresses the same way for an individual patch series,\n    ++until consensus is reached or the topic is dropped.\n     +\n     +\n     +Larger Discussions (without patches)\n    @@ Documentation/DecisionMaking.txt (new)\n     +even a single large patch series, or they might be more open-ended,\n     +policy-oriented discussions (examples:\n     +link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust]\n    -+or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving\n    -+submodule UX]). In either case, discussion progresses as described above for\n    -+general patch series.\n    ++or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving submodule UX]).\n    ++In either case, discussion progresses as described above for general patch series.\n     +\n     +For larger discussions without a patch series or other concrete implementation,\n     +it may be hard to judge when consensus has been reached, as there are not any\n    @@ Documentation/DecisionMaking.txt (new)\n     +restart discussion with an RFC patch series or other specific implementation\n     +that can be more easily debated.\n     +\n    -+If consensus around a decision has been reached but no implementation provided,\n    -+it is not the maintainer's responsibility to implement any particular decision.\n    ++When consensus is reached that it is a good idea, the original\n    ++proposer is expected to coordinate the effort to make it happen,\n    ++with help from others who were involved in the discussion, as\n    ++needed.\n    ++\n     +For decisions that require code changes, it is often the case that the original\n     +proposer will follow up with a patch series, although it is also common for\n     +other interested parties to provide an implementation (or parts of the\n    @@ Documentation/DecisionMaking.txt (new)\n     +\n     +For non-technical decisions such as community norms or processes, it is up to\n     +the community as a whole to implement and sustain agreed-upon changes.\n    ++The project leadership committe (PLC) may help the implementation of\n    ++policy decisions.\n     +\n     +\n     +Other Discussion Venues\n\n Documentation/DecisionMaking.txt | 74 ++++++++++++++++++++++++++++++++\n Documentation/Makefile           |  1 +\n 2 files changed, 75 insertions(+)\n create mode 100644 Documentation/DecisionMaking.txt\n\ndiff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt\nnew file mode 100644\nindex 0000000000..274ddfa62c\n--- /dev/null\n+++ b/Documentation/DecisionMaking.txt\n@@ -0,0 +1,74 @@\n+Decision-Making Process in the Git Project\n+==========================================\n+\n+Introduction\n+------------\n+This document describes the current decision-making process in the Git\n+project. It is a descriptive rather than prescriptive doc; that is, we want to\n+describe how things work in practice rather than explicitly recommending any\n+particular process or changes to the current process.\n+\n+Here we document how the project makes decisions for discussions\n+(with or without patches), in scale larger than an individual patch\n+series (which is fully covered by the SubmittingPatches document).\n+\n+\n+Larger Discussions (with patches)\n+---------------------------------\n+As with discussions on an individual patch series, starting a larger-scale\n+discussion often begins by sending a patch or series to the list. This might\n+take the form of an initial design doc, with implementation following in later\n+iterations of the series (for example,\n+link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding unit tests] or\n+link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based hooks]),\n+or it might include a full implementation from the beginning.\n+In either case, discussion progresses the same way for an individual patch series,\n+until consensus is reached or the topic is dropped.\n+\n+\n+Larger Discussions (without patches)\n+------------------------------------\n+Occasionally, larger discussions might occur without an associated patch series.\n+These might be very large-scale technical decisions that are beyond the scope of\n+even a single large patch series, or they might be more open-ended,\n+policy-oriented discussions (examples:\n+link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust]\n+or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving submodule UX]).\n+In either case, discussion progresses as described above for general patch series.\n+\n+For larger discussions without a patch series or other concrete implementation,\n+it may be hard to judge when consensus has been reached, as there are not any\n+official guidelines. If discussion stalls at this point, it may be helpful to\n+restart discussion with an RFC patch series or other specific implementation\n+that can be more easily debated.\n+\n+When consensus is reached that it is a good idea, the original\n+proposer is expected to coordinate the effort to make it happen,\n+with help from others who were involved in the discussion, as\n+needed.\n+\n+For decisions that require code changes, it is often the case that the original\n+proposer will follow up with a patch series, although it is also common for\n+other interested parties to provide an implementation (or parts of the\n+implementation, for very large changes).\n+\n+For non-technical decisions such as community norms or processes, it is up to\n+the community as a whole to implement and sustain agreed-upon changes.\n+The project leadership committe (PLC) may help the implementation of\n+policy decisions.\n+\n+\n+Other Discussion Venues\n+-----------------------\n+Occasionally decision proposals are presented off-list, e.g. at the semi-regular\n+Contributors' Summit. While higher-bandwidth face-to-face discussion is often\n+useful for quickly reaching consensus among attendees, generally we expect to\n+summarize the discussion in notes that can later be presented on-list. For an\n+example, see the thread\n+link:https://lore.kernel.org/git/AC2EB721-2979-43FD-922D-C5076A57F24B@jramsay.com.au/[Notes\n+from Git Contributor Summit, Los Angeles (April 5, 2020)] by James Ramsay.\n+\n+We prefer that \"official\" discussion happens on the list so that the full\n+community has opportunity to engage in discussion. This also means that the\n+mailing list archives contain a more-or-less complete history of project\n+discussions and decisions.\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3f2383a12c..a04da672c6 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -103,6 +103,7 @@ SP_ARTICLES += howto/coordinate-embargoed-releases\n API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))\n SP_ARTICLES += $(API_DOCS)\n \n+TECH_DOCS += DecisionMaking\n TECH_DOCS += ReviewingGuidelines\n TECH_DOCS += MyFirstContribution\n TECH_DOCS += MyFirstObjectWalk\n\nbase-commit: 436d4e5b14df49870a897f64fe92c0ddc7017e4c\n-- \n2.45.0.rc1.225.g2a3ae87e7f-goog\n\n"},{"id":"494915","messageId":"xmqq4jaxo1qu.fsf@gitster.g","threadId":"61325","inReplyTo":"5446ca49e042b104923ac2004d845a5f9018c9d9.1715894135.git.steadmon@google.com","subject":"Re: [PATCH v3] doc: describe the project's decision-making process","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-16T22:01:13Z","receivedAt":"2024-05-16T22:01:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Josh Steadmon <steadmon@google.com> writes:\n\n> Changes in V3:\n> * Squash in Junio's suggested patch to remove discussion of small-scale\n>   patch series.\n\nI do not think I deserve Co-authorship for the small changes in the\nremaining document, as my contributions going from v2 to v3 were\nmostly line removal ;-).\n\n> +Larger Discussions (with patches)\n> +---------------------------------\n\nReads well and looks sensible.\n\n> +Larger Discussions (without patches)\n> +------------------------------------\n> +Occasionally, larger discussions might occur without an associated patch series.\n> +These might be very large-scale technical decisions that are beyond the scope of\n> +...\n\nI do not know how strongly assertive you wanted to be, but I suspect\nthat it will read better with \"might\" -> \"may\".\n\n> ...\n> +For larger discussions without a patch series or other concrete implementation,\n> +it may be hard to judge when consensus has been reached, as there are not any\n> +official guidelines. If discussion stalls at this point, it may be helpful to\n> +restart discussion with an RFC patch series or other specific implementation\n> +that can be more easily debated.\n\nIt is a bit fuzzy what \"other specific implementation\" wants to\nconvey.  A mere \"RFC\" is often an unfinished work-in-progress, and\nif the \"other specific implementation\" is different from it, then\nwhat it would be?  A minimum viable product?  A proof-of-concept?\n\nAll other parts did read very well.\n\nNot that the above was unreadable, but just my reading hiccupped at\naround \"other specific implementation\".\n\nThanks.\n"},{"id":"494927","messageId":"Zkb5WeaTOLg9b5p8@tanuki","threadId":"61325","inReplyTo":"5446ca49e042b104923ac2004d845a5f9018c9d9.1715894135.git.steadmon@google.com","subject":"Re: [PATCH v3] doc: describe the project's decision-making process","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-17T06:29:45Z","receivedAt":"2024-05-17T06:29:52Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Thu, May 16, 2024 at 02:20:53PM -0700, Josh Steadmon wrote:\n[snip]\n> diff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt\n> new file mode 100644\n> index 0000000000..274ddfa62c\n> --- /dev/null\n> +++ b/Documentation/DecisionMaking.txt\n> @@ -0,0 +1,74 @@\n> +Decision-Making Process in the Git Project\n> +==========================================\n> +\n> +Introduction\n> +------------\n> +This document describes the current decision-making process in the Git\n> +project. It is a descriptive rather than prescriptive doc; that is, we want to\n> +describe how things work in practice rather than explicitly recommending any\n> +particular process or changes to the current process.\n\nNit: I think we _do_ want to recommend a process, but don't want to cast\nit into stone.\n\n[snip]\n> +Larger Discussions (without patches)\n> +------------------------------------\n> +Occasionally, larger discussions might occur without an associated patch series.\n> +These might be very large-scale technical decisions that are beyond the scope of\n> +even a single large patch series, or they might be more open-ended,\n> +policy-oriented discussions (examples:\n> +link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust]\n> +or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving submodule UX]).\n> +In either case, discussion progresses as described above for general patch series.\n> +\n> +For larger discussions without a patch series or other concrete implementation,\n> +it may be hard to judge when consensus has been reached, as there are not any\n> +official guidelines. If discussion stalls at this point, it may be helpful to\n> +restart discussion with an RFC patch series or other specific implementation\n> +that can be more easily debated.\n> +\n> +When consensus is reached that it is a good idea, the original\n> +proposer is expected to coordinate the effort to make it happen,\n> +with help from others who were involved in the discussion, as\n> +needed.\n\nOne thing I want to eventually propose is to go further here:\ndocumenting the outcome of the discussion, regardless of whether we\ndecided for or against it, in a low-overhead format. This could for\nexample be a small paragraph in a \"Documentation/Projects\" file that\npoints to the on-list discussion together with a small summary of why\nthe decision was reached.\n\nIn the case of the Rust discussion for example I think we ultimately\ndecided against it due to platform limitations of the toolchain. This\nlimitation will potentially go away at some point in time, and that\nwould allow us to revisit this discussion. Now if we had documented\nsomewhere that the decision against Rust was platform support, then it\nis easy to revive the discussion at a later point and point to that\nexact reason, arguing why it's not longer a problem now.\n\nI don't think that this change needs to be part of your patch though, as\nyour intent is only to document processes as they work right now. But I\nwanted to bring this up regardless as a foreshadowing.\n\nOverall this document looks good to me, thanks!\n\nPatrick\n"},{"id":"494982","messageId":"xmqqy188jst9.fsf@gitster.g","threadId":"61325","inReplyTo":"Zkb5WeaTOLg9b5p8@tanuki","subject":"Re: [PATCH v3] doc: describe the project's decision-making process","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-17T16:40:02Z","receivedAt":"2024-05-17T16:40:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n>> +This document describes the current decision-making process in the Git\n>> +project. It is a descriptive rather than prescriptive doc; that is, we want to\n>> +describe how things work in practice rather than explicitly recommending any\n>> +particular process or changes to the current process.\n>\n> Nit: I think we _do_ want to recommend a process, but don't want to cast\n> it into stone.\n\nYup.  How would we rephase it?  \"... rather than recommending an\nidealized process that we wish to use (but do not)?\"\n\n>> +When consensus is reached that it is a good idea, the original\n>> +proposer is expected to coordinate the effort to make it happen,\n>> +with help from others who were involved in the discussion, as\n>> +needed.\n>\n> One thing I want to eventually propose is to go further here:\n> documenting the outcome of the discussion, regardless of whether we\n> decided for or against it, in a low-overhead format. This could for\n> example be a small paragraph in a \"Documentation/Projects\" file that\n> points to the on-list discussion together with a small summary of why\n> the decision was reached.\n\nHaving such a list certainly is handy; the problem is how to keep\nthem current, though.\n\n> I don't think that this change needs to be part of your patch though, as\n> your intent is only to document processes as they work right now. But I\n> wanted to bring this up regardless as a foreshadowing.\n\nYup, I agree that it is probably better left out of the scope for\nnow.\n\nIf we are in the \"expressing wish\" mode, another thing we might find\nit useful, if such a thing existed, is a list of principles for\ndesigning new things.  E.g., not changing an established behaviour\nto prioritize protecting existing users' muscle memory over whims of\nthe day by folks who haven't had enough time to familialize with it.\nE.g., the plumbing output is sacred but the Porcelain output is\nsubject to change to improve human-user experience with coloring\nand pagination, etc.\n"},{"id":"494998","messageId":"xtndwhhpyizlgnr7aps4t2ly3cr4ivyncvmobf4xtowviq2ft6@l77pen6hlbgr","threadId":"61325","inReplyTo":"xmqq4jaxo1qu.fsf@gitster.g","subject":"Re: [PATCH v3] doc: describe the project's decision-making process","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2024-05-17T20:18:52Z","receivedAt":"2024-05-17T20:18:59Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"On 2024.05.16 15:01, Junio C Hamano wrote:\n> Josh Steadmon <steadmon@google.com> writes:\n> \n> > Changes in V3:\n> > * Squash in Junio's suggested patch to remove discussion of small-scale\n> >   patch series.\n> \n> I do not think I deserve Co-authorship for the small changes in the\n> remaining document, as my contributions going from v2 to v3 were\n> mostly line removal ;-).\n\nAll right, switched it to Helped-by :)\n\n> > +Larger Discussions (with patches)\n> > +---------------------------------\n> \n> Reads well and looks sensible.\n> \n> > +Larger Discussions (without patches)\n> > +------------------------------------\n> > +Occasionally, larger discussions might occur without an associated patch series.\n> > +These might be very large-scale technical decisions that are beyond the scope of\n> > +...\n> \n> I do not know how strongly assertive you wanted to be, but I suspect\n> that it will read better with \"might\" -> \"may\".\n\nFixed here and in the next line.\n\n> > ...\n> > +For larger discussions without a patch series or other concrete implementation,\n> > +it may be hard to judge when consensus has been reached, as there are not any\n> > +official guidelines. If discussion stalls at this point, it may be helpful to\n> > +restart discussion with an RFC patch series or other specific implementation\n> > +that can be more easily debated.\n> \n> It is a bit fuzzy what \"other specific implementation\" wants to\n> convey.  A mere \"RFC\" is often an unfinished work-in-progress, and\n> if the \"other specific implementation\" is different from it, then\n> what it would be?  A minimum viable product?  A proof-of-concept?\n\nAck, will reword this.\n\n> \n> All other parts did read very well.\n> \n> Not that the above was unreadable, but just my reading hiccupped at\n> around \"other specific implementation\".\n> \n> Thanks.\n"},{"id":"494999","messageId":"10f217915600eda3ebec886e4f020f87c22e318a.1715978031.git.steadmon@google.com","threadId":"61325","inReplyTo":"b2ef74c1b0c7482fa880a1519fd6ea1032df7789.1713222673.git.steadmon@google.com","subject":"[PATCH v4] doc: describe the project's decision-making process","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2024-05-17T20:35:44Z","receivedAt":"2024-05-17T20:35:47Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"The Git project currently operates according to an informal\nconsensus-building process, which is currently described in the\nSubmittingPatches document. However, that focuses on small/medium-scale\npatch series. For larger-scale decisions, the process is not as well\ndescribed. Document what to expect so that we have something concrete to\nhelp inform newcomers to the project.\n\nThis document explicitly does not aim to impose a formal process to\ndecision-making, nor to change pre-existing norms. Its only aim is to\ndescribe how the project currently operates today.\n\nHelped-by: Junio C Hamano <gitster@pobox.com>\nSigned-off-by: Josh Steadmon <steadmon@google.com>\n---\n\nChanges in V4:\n* Minor wording cleanups to be more emphatic and to clarify \"other\n  specific implementation\" phrase.\n\nChanges in V3:\n* Squash in Junio's suggested patch to remove discussion of small-scale\n  patch series.\n\nChanges in V2:\n* Split doc to treat patch series discussion as the general case, with\n  larger discussions (with or without patches) as special situations.\n* Add links to example discussions for certain situations\n* Add link to contributor summit notes\n* Add link to Code of Conduct doc\n* Add justification for keeping discussion on-list\n* Add paragraph about explicit negative consensus\n* Minor reword of advice on when to CC experts\n* Minor reword of doc intro to avoid indecisive text\n\nRange-diff against v3:\n1:  5446ca49e0 ! 1:  10f2179156 doc: describe the project's decision-making process\n    @@ Commit message\n         describe how the project currently operates today.\n     \n    -    Co-authored-by: Junio C Hamano <gitster@pobox.com>\n    +    Helped-by: Junio C Hamano <gitster@pobox.com>\n     \n      ## Documentation/DecisionMaking.txt (new) ##\n     @@\n    @@ Documentation/DecisionMaking.txt (new)\n     +Larger Discussions (without patches)\n     +------------------------------------\n     +Occasionally, larger discussions might occur without an associated patch series.\n    -+These might be very large-scale technical decisions that are beyond the scope of\n    -+even a single large patch series, or they might be more open-ended,\n    ++These may be very large-scale technical decisions that are beyond the scope of\n    ++even a single large patch series, or they may be more open-ended,\n     +policy-oriented discussions (examples:\n     +link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust]\n     +or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving submodule UX]).\n    @@ Documentation/DecisionMaking.txt (new)\n     +For larger discussions without a patch series or other concrete implementation,\n     +it may be hard to judge when consensus has been reached, as there are not any\n     +official guidelines. If discussion stalls at this point, it may be helpful to\n    -+restart discussion with an RFC patch series or other specific implementation\n    -+that can be more easily debated.\n    ++restart discussion with an RFC patch series (such as a partial, unfinished\n    ++implementation or proof of concept) that can be more easily debated.\n     +\n     +When consensus is reached that it is a good idea, the original\n     +proposer is expected to coordinate the effort to make it happen,\n\n Documentation/DecisionMaking.txt | 74 ++++++++++++++++++++++++++++++++\n Documentation/Makefile           |  1 +\n 2 files changed, 75 insertions(+)\n create mode 100644 Documentation/DecisionMaking.txt\n\ndiff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt\nnew file mode 100644\nindex 0000000000..dbb4c1f569\n--- /dev/null\n+++ b/Documentation/DecisionMaking.txt\n@@ -0,0 +1,74 @@\n+Decision-Making Process in the Git Project\n+==========================================\n+\n+Introduction\n+------------\n+This document describes the current decision-making process in the Git\n+project. It is a descriptive rather than prescriptive doc; that is, we want to\n+describe how things work in practice rather than explicitly recommending any\n+particular process or changes to the current process.\n+\n+Here we document how the project makes decisions for discussions\n+(with or without patches), in scale larger than an individual patch\n+series (which is fully covered by the SubmittingPatches document).\n+\n+\n+Larger Discussions (with patches)\n+---------------------------------\n+As with discussions on an individual patch series, starting a larger-scale\n+discussion often begins by sending a patch or series to the list. This might\n+take the form of an initial design doc, with implementation following in later\n+iterations of the series (for example,\n+link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding unit tests] or\n+link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based hooks]),\n+or it might include a full implementation from the beginning.\n+In either case, discussion progresses the same way for an individual patch series,\n+until consensus is reached or the topic is dropped.\n+\n+\n+Larger Discussions (without patches)\n+------------------------------------\n+Occasionally, larger discussions might occur without an associated patch series.\n+These may be very large-scale technical decisions that are beyond the scope of\n+even a single large patch series, or they may be more open-ended,\n+policy-oriented discussions (examples:\n+link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust]\n+or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving submodule UX]).\n+In either case, discussion progresses as described above for general patch series.\n+\n+For larger discussions without a patch series or other concrete implementation,\n+it may be hard to judge when consensus has been reached, as there are not any\n+official guidelines. If discussion stalls at this point, it may be helpful to\n+restart discussion with an RFC patch series (such as a partial, unfinished\n+implementation or proof of concept) that can be more easily debated.\n+\n+When consensus is reached that it is a good idea, the original\n+proposer is expected to coordinate the effort to make it happen,\n+with help from others who were involved in the discussion, as\n+needed.\n+\n+For decisions that require code changes, it is often the case that the original\n+proposer will follow up with a patch series, although it is also common for\n+other interested parties to provide an implementation (or parts of the\n+implementation, for very large changes).\n+\n+For non-technical decisions such as community norms or processes, it is up to\n+the community as a whole to implement and sustain agreed-upon changes.\n+The project leadership committe (PLC) may help the implementation of\n+policy decisions.\n+\n+\n+Other Discussion Venues\n+-----------------------\n+Occasionally decision proposals are presented off-list, e.g. at the semi-regular\n+Contributors' Summit. While higher-bandwidth face-to-face discussion is often\n+useful for quickly reaching consensus among attendees, generally we expect to\n+summarize the discussion in notes that can later be presented on-list. For an\n+example, see the thread\n+link:https://lore.kernel.org/git/AC2EB721-2979-43FD-922D-C5076A57F24B@jramsay.com.au/[Notes\n+from Git Contributor Summit, Los Angeles (April 5, 2020)] by James Ramsay.\n+\n+We prefer that \"official\" discussion happens on the list so that the full\n+community has opportunity to engage in discussion. This also means that the\n+mailing list archives contain a more-or-less complete history of project\n+discussions and decisions.\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3f2383a12c..a04da672c6 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -103,6 +103,7 @@ SP_ARTICLES += howto/coordinate-embargoed-releases\n API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))\n SP_ARTICLES += $(API_DOCS)\n \n+TECH_DOCS += DecisionMaking\n TECH_DOCS += ReviewingGuidelines\n TECH_DOCS += MyFirstContribution\n TECH_DOCS += MyFirstObjectWalk\n\nbase-commit: 436d4e5b14df49870a897f64fe92c0ddc7017e4c\n-- \n2.45.0.rc1.225.g2a3ae87e7f-goog\n\n"},{"id":"495001","messageId":"xmqqa5kof5ql.fsf@gitster.g","threadId":"61325","inReplyTo":"10f217915600eda3ebec886e4f020f87c22e318a.1715978031.git.steadmon@google.com","subject":"Re: [PATCH v4] doc: describe the project's decision-making process","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-17T22:12:02Z","receivedAt":"2024-05-17T22:12:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Josh Steadmon <steadmon@google.com> writes:\n\n> The Git project currently operates according to an informal\n> consensus-building process, which is currently described in the\n> SubmittingPatches document. However, that focuses on small/medium-scale\n> patch series. For larger-scale decisions, the process is not as well\n> described. Document what to expect so that we have something concrete to\n> help inform newcomers to the project.\n>\n> This document explicitly does not aim to impose a formal process to\n> decision-making, nor to change pre-existing norms. Its only aim is to\n> describe how the project currently operates today.\n>\n> Helped-by: Junio C Hamano <gitster@pobox.com>\n> Signed-off-by: Josh Steadmon <steadmon@google.com>\n> ---\n>\n> Changes in V4:\n> * Minor wording cleanups to be more emphatic and to clarify \"other\n>   specific implementation\" phrase.\n\nThanks for an update.  I am myself undecided on the \"explicit\nrecommendation?\" question Patrick posed, but other than that this\niteration looked reasonable.\n\nQueued.  Thanks.\n"},{"id":"495141","messageId":"Zkw3cWb_jiY1afUZ@tanuki","threadId":"61325","inReplyTo":"xmqqy188jst9.fsf@gitster.g","subject":"Re: [PATCH v3] doc: describe the project's decision-making process","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-21T05:56:01Z","receivedAt":"2024-05-21T05:56:09Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Fri, May 17, 2024 at 09:40:02AM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt <ps@pks.im> writes:\n> >> +When consensus is reached that it is a good idea, the original\n> >> +proposer is expected to coordinate the effort to make it happen,\n> >> +with help from others who were involved in the discussion, as\n> >> +needed.\n> >\n> > One thing I want to eventually propose is to go further here:\n> > documenting the outcome of the discussion, regardless of whether we\n> > decided for or against it, in a low-overhead format. This could for\n> > example be a small paragraph in a \"Documentation/Projects\" file that\n> > points to the on-list discussion together with a small summary of why\n> > the decision was reached.\n> \n> Having such a list certainly is handy; the problem is how to keep\n> them current, though.\n\nI try to somewhat tackle the issue by explicitly saying that the format\nshould be low-overhead. But that of course won't fully make the problem\ngo away, we still need to make sure that it's getting updated somewhat\nregularly.\n\nThat being said, I don't think it'll be all that often that we need to\nadd new items to the list. We don't have a ton of large ongoing projects\nin our codebase. I'd claim that we can rather measure the cadence of\nsuch projects in years rather than months. So we might get away with a\n\"best effort\" approach to keep it up-to-date.\n\n> > I don't think that this change needs to be part of your patch though, as\n> > your intent is only to document processes as they work right now. But I\n> > wanted to bring this up regardless as a foreshadowing.\n> \n> Yup, I agree that it is probably better left out of the scope for\n> now.\n> \n> If we are in the \"expressing wish\" mode, another thing we might find\n> it useful, if such a thing existed, is a list of principles for\n> designing new things.  E.g., not changing an established behaviour\n> to prioritize protecting existing users' muscle memory over whims of\n> the day by folks who haven't had enough time to familialize with it.\n> E.g., the plumbing output is sacred but the Porcelain output is\n> subject to change to improve human-user experience with coloring\n> and pagination, etc.\n\nYes, I very much agree. One of these principles that I want to discuss\nsoonish is the design of our CLI. I think we would benefit if we had a\nset of guidelines that show what our ideal UI should look like. Many of\nour older commands may not fit into such a UI design, as I think that it\nhas evolved since the inception of Git, and that's fine. But starting to\nthink about the bigger picture here and where we want to go may be quite\nhelpful overall. It would make it a ton easier for folks to argue based\non established and documented principles instead of requiring handwavy\ngut feeling.\n\nThat's only one part though where we may want to lay out our principles,\nI'm sure there are others. But I'm throttling my push for more structure\na bit, and rather want to lead one discussion after the other.\n\nPatrick\n"},{"id":"495142","messageId":"Zkw39J_anOIk-zp1@tanuki","threadId":"61325","inReplyTo":"xmqqa5kof5ql.fsf@gitster.g","subject":"Re: [PATCH v4] doc: describe the project's decision-making process","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-21T05:58:12Z","receivedAt":"2024-05-21T05:58:17Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Fri, May 17, 2024 at 03:12:02PM -0700, Junio C Hamano wrote:\n> Josh Steadmon <steadmon@google.com> writes:\n> \n> > The Git project currently operates according to an informal\n> > consensus-building process, which is currently described in the\n> > SubmittingPatches document. However, that focuses on small/medium-scale\n> > patch series. For larger-scale decisions, the process is not as well\n> > described. Document what to expect so that we have something concrete to\n> > help inform newcomers to the project.\n> >\n> > This document explicitly does not aim to impose a formal process to\n> > decision-making, nor to change pre-existing norms. Its only aim is to\n> > describe how the project currently operates today.\n> >\n> > Helped-by: Junio C Hamano <gitster@pobox.com>\n> > Signed-off-by: Josh Steadmon <steadmon@google.com>\n> > ---\n> >\n> > Changes in V4:\n> > * Minor wording cleanups to be more emphatic and to clarify \"other\n> >   specific implementation\" phrase.\n> \n> Thanks for an update.  I am myself undecided on the \"explicit\n> recommendation?\" question Patrick posed, but other than that this\n> iteration looked reasonable.\n> \n> Queued.  Thanks.\n\nI think the current version is good enough, we can still iterate on it\nas needed. Thanks!\n\nPatrick\n"}]}