| Message ID | 5446ca49e042b104923ac2004d845a5f9018c9d9.1715894135.git.steadmon@google.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v3] doc: describe the project's decision-making process | expand |
Josh Steadmon <steadmon@google.com> writes: > Changes in V3: > * Squash in Junio's suggested patch to remove discussion of small-scale > patch series. I do not think I deserve Co-authorship for the small changes in the remaining document, as my contributions going from v2 to v3 were mostly line removal ;-). > +Larger Discussions (with patches) > +--------------------------------- Reads well and looks sensible. > +Larger Discussions (without patches) > +------------------------------------ > +Occasionally, larger discussions might occur without an associated patch series. > +These might be very large-scale technical decisions that are beyond the scope of > +... I do not know how strongly assertive you wanted to be, but I suspect that it will read better with "might" -> "may". > ... > +For larger discussions without a patch series or other concrete implementation, > +it may be hard to judge when consensus has been reached, as there are not any > +official guidelines. If discussion stalls at this point, it may be helpful to > +restart discussion with an RFC patch series or other specific implementation > +that can be more easily debated. It is a bit fuzzy what "other specific implementation" wants to convey. A mere "RFC" is often an unfinished work-in-progress, and if the "other specific implementation" is different from it, then what it would be? A minimum viable product? A proof-of-concept? All other parts did read very well. Not that the above was unreadable, but just my reading hiccupped at around "other specific implementation". Thanks.
On Thu, May 16, 2024 at 02:20:53PM -0700, Josh Steadmon wrote: [snip] > diff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt > new file mode 100644 > index 0000000000..274ddfa62c > --- /dev/null > +++ b/Documentation/DecisionMaking.txt > @@ -0,0 +1,74 @@ > +Decision-Making Process in the Git Project > +========================================== > + > +Introduction > +------------ > +This document describes the current decision-making process in the Git > +project. It is a descriptive rather than prescriptive doc; that is, we want to > +describe how things work in practice rather than explicitly recommending any > +particular process or changes to the current process. Nit: I think we _do_ want to recommend a process, but don't want to cast it into stone. [snip] > +Larger Discussions (without patches) > +------------------------------------ > +Occasionally, larger discussions might occur without an associated patch series. > +These might be very large-scale technical decisions that are beyond the scope of > +even a single large patch series, or they might be more open-ended, > +policy-oriented discussions (examples: > +link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust] > +or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving submodule UX]). > +In either case, discussion progresses as described above for general patch series. > + > +For larger discussions without a patch series or other concrete implementation, > +it may be hard to judge when consensus has been reached, as there are not any > +official guidelines. If discussion stalls at this point, it may be helpful to > +restart discussion with an RFC patch series or other specific implementation > +that can be more easily debated. > + > +When consensus is reached that it is a good idea, the original > +proposer is expected to coordinate the effort to make it happen, > +with help from others who were involved in the discussion, as > +needed. One thing I want to eventually propose is to go further here: documenting the outcome of the discussion, regardless of whether we decided for or against it, in a low-overhead format. This could for example be a small paragraph in a "Documentation/Projects" file that points to the on-list discussion together with a small summary of why the decision was reached. In the case of the Rust discussion for example I think we ultimately decided against it due to platform limitations of the toolchain. This limitation will potentially go away at some point in time, and that would allow us to revisit this discussion. Now if we had documented somewhere that the decision against Rust was platform support, then it is easy to revive the discussion at a later point and point to that exact reason, arguing why it's not longer a problem now. I don't think that this change needs to be part of your patch though, as your intent is only to document processes as they work right now. But I wanted to bring this up regardless as a foreshadowing. Overall this document looks good to me, thanks! Patrick
Patrick Steinhardt <ps@pks.im> writes: >> +This document describes the current decision-making process in the Git >> +project. It is a descriptive rather than prescriptive doc; that is, we want to >> +describe how things work in practice rather than explicitly recommending any >> +particular process or changes to the current process. > > Nit: I think we _do_ want to recommend a process, but don't want to cast > it into stone. Yup. How would we rephase it? "... rather than recommending an idealized process that we wish to use (but do not)?" >> +When consensus is reached that it is a good idea, the original >> +proposer is expected to coordinate the effort to make it happen, >> +with help from others who were involved in the discussion, as >> +needed. > > One thing I want to eventually propose is to go further here: > documenting the outcome of the discussion, regardless of whether we > decided for or against it, in a low-overhead format. This could for > example be a small paragraph in a "Documentation/Projects" file that > points to the on-list discussion together with a small summary of why > the decision was reached. Having such a list certainly is handy; the problem is how to keep them current, though. > I don't think that this change needs to be part of your patch though, as > your intent is only to document processes as they work right now. But I > wanted to bring this up regardless as a foreshadowing. Yup, I agree that it is probably better left out of the scope for now. If we are in the "expressing wish" mode, another thing we might find it useful, if such a thing existed, is a list of principles for designing new things. E.g., not changing an established behaviour to prioritize protecting existing users' muscle memory over whims of the day by folks who haven't had enough time to familialize with it. E.g., the plumbing output is sacred but the Porcelain output is subject to change to improve human-user experience with coloring and pagination, etc.
On 2024.05.16 15:01, Junio C Hamano wrote: > Josh Steadmon <steadmon@google.com> writes: > > > Changes in V3: > > * Squash in Junio's suggested patch to remove discussion of small-scale > > patch series. > > I do not think I deserve Co-authorship for the small changes in the > remaining document, as my contributions going from v2 to v3 were > mostly line removal ;-). All right, switched it to Helped-by :) > > +Larger Discussions (with patches) > > +--------------------------------- > > Reads well and looks sensible. > > > +Larger Discussions (without patches) > > +------------------------------------ > > +Occasionally, larger discussions might occur without an associated patch series. > > +These might be very large-scale technical decisions that are beyond the scope of > > +... > > I do not know how strongly assertive you wanted to be, but I suspect > that it will read better with "might" -> "may". Fixed here and in the next line. > > ... > > +For larger discussions without a patch series or other concrete implementation, > > +it may be hard to judge when consensus has been reached, as there are not any > > +official guidelines. If discussion stalls at this point, it may be helpful to > > +restart discussion with an RFC patch series or other specific implementation > > +that can be more easily debated. > > It is a bit fuzzy what "other specific implementation" wants to > convey. A mere "RFC" is often an unfinished work-in-progress, and > if the "other specific implementation" is different from it, then > what it would be? A minimum viable product? A proof-of-concept? Ack, will reword this. > > All other parts did read very well. > > Not that the above was unreadable, but just my reading hiccupped at > around "other specific implementation". > > Thanks.
On Fri, May 17, 2024 at 09:40:02AM -0700, Junio C Hamano wrote: > Patrick Steinhardt <ps@pks.im> writes: > >> +When consensus is reached that it is a good idea, the original > >> +proposer is expected to coordinate the effort to make it happen, > >> +with help from others who were involved in the discussion, as > >> +needed. > > > > One thing I want to eventually propose is to go further here: > > documenting the outcome of the discussion, regardless of whether we > > decided for or against it, in a low-overhead format. This could for > > example be a small paragraph in a "Documentation/Projects" file that > > points to the on-list discussion together with a small summary of why > > the decision was reached. > > Having such a list certainly is handy; the problem is how to keep > them current, though. I try to somewhat tackle the issue by explicitly saying that the format should be low-overhead. But that of course won't fully make the problem go away, we still need to make sure that it's getting updated somewhat regularly. That being said, I don't think it'll be all that often that we need to add new items to the list. We don't have a ton of large ongoing projects in our codebase. I'd claim that we can rather measure the cadence of such projects in years rather than months. So we might get away with a "best effort" approach to keep it up-to-date. > > I don't think that this change needs to be part of your patch though, as > > your intent is only to document processes as they work right now. But I > > wanted to bring this up regardless as a foreshadowing. > > Yup, I agree that it is probably better left out of the scope for > now. > > If we are in the "expressing wish" mode, another thing we might find > it useful, if such a thing existed, is a list of principles for > designing new things. E.g., not changing an established behaviour > to prioritize protecting existing users' muscle memory over whims of > the day by folks who haven't had enough time to familialize with it. > E.g., the plumbing output is sacred but the Porcelain output is > subject to change to improve human-user experience with coloring > and pagination, etc. Yes, I very much agree. One of these principles that I want to discuss soonish is the design of our CLI. I think we would benefit if we had a set of guidelines that show what our ideal UI should look like. Many of our older commands may not fit into such a UI design, as I think that it has evolved since the inception of Git, and that's fine. But starting to think about the bigger picture here and where we want to go may be quite helpful overall. It would make it a ton easier for folks to argue based on established and documented principles instead of requiring handwavy gut feeling. That's only one part though where we may want to lay out our principles, I'm sure there are others. But I'm throttling my push for more structure a bit, and rather want to lead one discussion after the other. Patrick
diff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt new file mode 100644 index 0000000000..274ddfa62c --- /dev/null +++ b/Documentation/DecisionMaking.txt @@ -0,0 +1,74 @@ +Decision-Making Process in the Git Project +========================================== + +Introduction +------------ +This document describes the current decision-making process in the Git +project. It is a descriptive rather than prescriptive doc; that is, we want to +describe how things work in practice rather than explicitly recommending any +particular process or changes to the current process. + +Here we document how the project makes decisions for discussions +(with or without patches), in scale larger than an individual patch +series (which is fully covered by the SubmittingPatches document). + + +Larger Discussions (with patches) +--------------------------------- +As with discussions on an individual patch series, starting a larger-scale +discussion often begins by sending a patch or series to the list. This might +take the form of an initial design doc, with implementation following in later +iterations of the series (for example, +link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding unit tests] or +link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based hooks]), +or it might include a full implementation from the beginning. +In either case, discussion progresses the same way for an individual patch series, +until consensus is reached or the topic is dropped. + + +Larger Discussions (without patches) +------------------------------------ +Occasionally, larger discussions might occur without an associated patch series. +These might be very large-scale technical decisions that are beyond the scope of +even a single large patch series, or they might be more open-ended, +policy-oriented discussions (examples: +link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust] +or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving submodule UX]). +In either case, discussion progresses as described above for general patch series. + +For larger discussions without a patch series or other concrete implementation, +it may be hard to judge when consensus has been reached, as there are not any +official guidelines. If discussion stalls at this point, it may be helpful to +restart discussion with an RFC patch series or other specific implementation +that can be more easily debated. + +When consensus is reached that it is a good idea, the original +proposer is expected to coordinate the effort to make it happen, +with help from others who were involved in the discussion, as +needed. + +For decisions that require code changes, it is often the case that the original +proposer will follow up with a patch series, although it is also common for +other interested parties to provide an implementation (or parts of the +implementation, for very large changes). + +For non-technical decisions such as community norms or processes, it is up to +the community as a whole to implement and sustain agreed-upon changes. +The project leadership committe (PLC) may help the implementation of +policy decisions. + + +Other Discussion Venues +----------------------- +Occasionally decision proposals are presented off-list, e.g. at the semi-regular +Contributors' Summit. While higher-bandwidth face-to-face discussion is often +useful for quickly reaching consensus among attendees, generally we expect to +summarize the discussion in notes that can later be presented on-list. For an +example, see the thread +link:https://lore.kernel.org/git/AC2EB721-2979-43FD-922D-C5076A57F24B@jramsay.com.au/[Notes +from Git Contributor Summit, Los Angeles (April 5, 2020)] by James Ramsay. + +We prefer that "official" discussion happens on the list so that the full +community has opportunity to engage in discussion. This also means that the +mailing list archives contain a more-or-less complete history of project +discussions and decisions. diff --git a/Documentation/Makefile b/Documentation/Makefile index 3f2383a12c..a04da672c6 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -103,6 +103,7 @@ SP_ARTICLES += howto/coordinate-embargoed-releases API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) SP_ARTICLES += $(API_DOCS) +TECH_DOCS += DecisionMaking TECH_DOCS += ReviewingGuidelines TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk
The Git project currently operates according to an informal consensus-building process, which is currently described in the SubmittingPatches document. However, that focuses on small/medium-scale patch series. For larger-scale decisions, the process is not as well described. Document what to expect so that we have something concrete to help inform newcomers to the project. This document explicitly does not aim to impose a formal process to decision-making, nor to change pre-existing norms. Its only aim is to describe how the project currently operates today. Co-authored-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Josh Steadmon <steadmon@google.com> --- doc: describe the project's decision-making process Changes in V3: * Squash in Junio's suggested patch to remove discussion of small-scale patch series. Changes in V2: * Split doc to treat patch series discussion as the general case, with larger discussions (with or without patches) as special situations. * Add links to example discussions for certain situations * Add link to contributor summit notes * Add link to Code of Conduct doc * Add justification for keeping discussion on-list * Add paragraph about explicit negative consensus * Minor reword of advice on when to CC experts * MInor reword of doc intro to avoid indecisive text Range-diff against v2: 1: 4a829792bf ! 1: 5446ca49e0 doc: describe the project's decision-making process @@ Commit message doc: describe the project's decision-making process The Git project currently operates according to an informal - consensus-building process, which is not currently well-described. - Document what to expect so that we have something concrete to help - inform newcomers to the project. + consensus-building process, which is currently described in the + SubmittingPatches document. However, that focuses on small/medium-scale + patch series. For larger-scale decisions, the process is not as well + described. Document what to expect so that we have something concrete to + help inform newcomers to the project. This document explicitly does not aim to impose a formal process to decision-making, nor to change pre-existing norms. Its only aim is to describe how the project currently operates today. + Co-authored-by: Junio C Hamano <gitster@pobox.com> ## Documentation/DecisionMaking.txt (new) ## @@ @@ Documentation/DecisionMaking.txt (new) + +Introduction +------------ -+This doc aims to describe the current decision-making process in the Git ++This document describes the current decision-making process in the Git +project. It is a descriptive rather than prescriptive doc; that is, we want to +describe how things work in practice rather than explicitly recommending any +particular process or changes to the current process. + -+Here we document how the project makes decisions for general patch series, and -+for larger-scale discussions (with or without patches). -+ -+ -+General Patch Series -+-------------------- -+ -+Starting a Discussion -+~~~~~~~~~~~~~~~~~~~~~ -+For most changes, discussions are started by sending a patch series to the list. -+There is rarely any need to discuss or ask for approval prior to sending -+patches; the merit of both the general idea behind your change and the code to -+implement it will be discussed at the same time. -+ -+NOTE: For general guides on creating and sending a patch series to the list, see -+link:SubmittingPatches.html[SubmittingPatches] and -+link:MyFirstContribution.html[MyFirstContribution]. The remainder of this -+doc will focus more on what to expect from the list discussion. -+ -+Because members of the Git community have a wide variety of experience, -+backgrounds, and values, series are expected to include as much context as -+possible. -+ -+If the proposer is aware of individuals with an interest in the subject of the -+change, it is helpful to CC them on the proposal to increase the likelihood of -+receiving constructive feedback. -+ -+Engaging in Discussion -+~~~~~~~~~~~~~~~~~~~~~~ -+Once a proposal has been made, the community will discuss it on-list. While the -+maintainer will often participate in discussions, it is not the maintainer's -+responsibility to guide discussion; the proposer and any other interested -+parties are expected to stay engaged in the discussion and ensure progress is -+made. -+ -+Anyone with an interest in the topic is welcome to discuss the matter. It is -+expected that all discussion will adhere to the link:../CODE_OF_CONDUCT.md[Code -+of Conduct] rules. -+ -+Finalizing a Decision -+~~~~~~~~~~~~~~~~~~~~~ -+If the maintainer judges that positive consensus has been reached on a topic, -+they will merge the series, usually to the 'next' integration branch. After a -+suitable period of time for testing by the community, changes are merged from -+'next' into 'master', from which official releases are tagged. -+ -+If consensus has not been reached, discussion may continue, or the proposal may -+be abandoned if no one continues discussion. More rarely, explicit negative -+consensus may be reached if the community feels that the series is not suitable, -+in which case the series should be dropped and discussion ended. -+ -+There are no strict guidelines used to judge when consensus has been reached, -+but generally we expect all points of feedback to have been addressed with -+either a fix or an explanation on why no change is necessary. ++Here we document how the project makes decisions for discussions ++(with or without patches), in scale larger than an individual patch ++series (which is fully covered by the SubmittingPatches document). + + +Larger Discussions (with patches) +--------------------------------- -+As with discussions on a general patch series, starting a larger-scale ++As with discussions on an individual patch series, starting a larger-scale +discussion often begins by sending a patch or series to the list. This might +take the form of an initial design doc, with implementation following in later +iterations of the series (for example, -+link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding -+unit tests] or -+link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based -+hooks]), or it might include a full implementation from the beginning. In either -+case, discussion progresses as described above until consensus is reached or the -+topic is dropped. ++link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding unit tests] or ++link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based hooks]), ++or it might include a full implementation from the beginning. ++In either case, discussion progresses the same way for an individual patch series, ++until consensus is reached or the topic is dropped. + + +Larger Discussions (without patches) @@ Documentation/DecisionMaking.txt (new) +even a single large patch series, or they might be more open-ended, +policy-oriented discussions (examples: +link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust] -+or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving -+submodule UX]). In either case, discussion progresses as described above for -+general patch series. ++or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving submodule UX]). ++In either case, discussion progresses as described above for general patch series. + +For larger discussions without a patch series or other concrete implementation, +it may be hard to judge when consensus has been reached, as there are not any @@ Documentation/DecisionMaking.txt (new) +restart discussion with an RFC patch series or other specific implementation +that can be more easily debated. + -+If consensus around a decision has been reached but no implementation provided, -+it is not the maintainer's responsibility to implement any particular decision. ++When consensus is reached that it is a good idea, the original ++proposer is expected to coordinate the effort to make it happen, ++with help from others who were involved in the discussion, as ++needed. ++ +For decisions that require code changes, it is often the case that the original +proposer will follow up with a patch series, although it is also common for +other interested parties to provide an implementation (or parts of the @@ Documentation/DecisionMaking.txt (new) + +For non-technical decisions such as community norms or processes, it is up to +the community as a whole to implement and sustain agreed-upon changes. ++The project leadership committe (PLC) may help the implementation of ++policy decisions. + + +Other Discussion Venues Documentation/DecisionMaking.txt | 74 ++++++++++++++++++++++++++++++++ Documentation/Makefile | 1 + 2 files changed, 75 insertions(+) create mode 100644 Documentation/DecisionMaking.txt base-commit: 436d4e5b14df49870a897f64fe92c0ddc7017e4c