From 58e6875a434f8f909e4644a7607fea2138a56937 Mon Sep 17 00:00:00 2001 From: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> Date: Fri, 10 Mar 2023 10:18:28 +1100 Subject: [PATCH 01/14] WIP --- CONSENT_DECISION_MAKING.md | 269 +++++++++++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) create mode 100644 CONSENT_DECISION_MAKING.md diff --git a/CONSENT_DECISION_MAKING.md b/CONSENT_DECISION_MAKING.md new file mode 100644 index 00000000000..91f0fa072c9 --- /dev/null +++ b/CONSENT_DECISION_MAKING.md @@ -0,0 +1,269 @@ +# Consent decision-making + +The Openverse maintainers have elected to adopt a decision-making model based on +the +[Sociocracy practice of "consent decision-making"](https://patterns.sociocracy30.org/consent-decision-making.html). +We hope this will accomplish the following: + +- Bring expediency to decision-making by giving guidelines for how and what + types of feedback to give +- Adopt more specific standards about what types of feedback must be addressed + before a proposal can be ratified for implementation +- Give specificity in feedback expectations, both for who will participate in a + decision-making process and what responsibilities and tools they have for + participating +- Reaffirm trust between contributors when evaluating proposals + +Historically, each of these have presented problems for the Openverse project as +it has grown. Decision-making can drag on for months, proposal reviews get stuck +in feedback cycles over issues that could be addressed later on, and there were +few, if any, expectations around who would participate in a discussion or what +the expectations of that participation was. Adopting the process described +below, we hope, will address some of the underlying causes of these problems, in +addition to the benefits described above. + +The process described below is heavily modified from the regular Sociocratic +process. The differences come from two directions: + +- The needs of a largely asynchronously coordinated base of contributors +- Internal feedback and iteration on the initial process, even after + modification for asynchrony + +**This process is not set in stone.** Nor is it a set of laws that must be +followed at all times. This document uses prescriptive language filled with +imperatives primarily to prevent the process itself from being filled with +contingencies at every turn. However, as with every other aspect of our ever +evolving processes, these are merely suggestions that we expect contributors to +adhere to. They cannot cover every situation and undoubtedly there are +exceptional situations where following these suggestions to the letter would be +antithetical to the goals of the project and even of the process itself. + +If during your time as an Openverse contributor, you feel there are ways in +which this process can be improved and iterated upon, please know that this +process should be iterated upon and that suggestions for improvement are open +from any contributor to the project. + +## Terms + +- "Author": The person making the proposal. +- "Participants": All participants of the decision-making process, including the + author, the requested participants, and ad-hoc participants. +- "Reactions": A broad class of feedback that can include personal preferences + as well as general scepticisms about the validity or safety of the solutions + described in the proposal. +- "Question": A request for clarification or explanation of an aspect of the + proposal. Questions may also request additional information be added to the + proposal. +- "Objection": An explained uncertainty about the appropriateness, efficacy, or + safety of a solution +- "Paramount objection": An objection outlining an issue that would cause harm + to the project or its contributors; especially issues that could cause harm + and are difficult to reverse and not strictly necessary to accomplish the + goals of the project +- "Ratified proposal": A proposal that has undergone the formal decision-making + process and has been accepted as a valid solution for the problem it tries to + address by the participants of the discussion. +- "Process proposal": A proposal to change processes followed by the + contributors in the course of stewarding the project towards success. +- "Purpose": The motivation for the proposal. This often includes the problem + the proposal aims to solve. In the original Sociocratic model this is called + the "driver". + +## Major differences from the original process + +### Reactions + +Reactions can be shared at any time. Be careful to ensure that they're not +objections (which should, with few exceptions, be reserved for the objection +round). Examples of reactions are: + +- "I love this approach" +- "I like this proposal, but I don't understand X part of it yet" +- "I don't think this will work, but I left some questions to clarify the areas + I have concerns over" +- "I don't understand the underlying problem, so the solution seems too abstract + to me" +- "I don't think this solution will solve the problem as described" + +Note that these are not questions (they do not ask for clarification) nor are +they objections (they do not point to specific problems with the proposed +solution). + +### Removal of initial rounds + +Because our process is primarily asynchronous, because our decision-making +happens in public, and because the outcomes of our discussions are ultimately +documented in GitHub or other accessible venues, we can skip some of the initial +stages. Specifically, the "consent to driver" and the "present the proposal" +stages cannot work in the same way. Typically, the purpose of a proposal will +have been clarified through a previous discussion. Proposals raised without +prior "buy-in" from other contributors should be done so carefully, with the +understanding that participants may question the purpose and need for the +proposal. The presentation of a proposal happens implicitly when the GitHub PR +or discussion is opened to contain the proposal, so we do not need a special +step for this. + +## Process summary + +Full descriptions of each of these stages of discussion are below. This section +is meant as a summary for getting an initial overview for people new to the +process or refreshing the broad intentions for folks already familiar with it. + +These steps are ordered and must be followed in the order they are presented +here. + +1. Question stage + - Suggested span: 3 days + - Goal: clarify the proposal and uncover initial uncertainties or issues + - Note: at this point, participants may question the purpose of the proposal + if it was not previously agreed upon in a previous discussion. If the + proposal was requested as a product of an earlier discussion, then the + purpose was already agreed upon and should not itself come under question. +2. Revision stage + - There is no suggested time span, but the author should clearly note when + they expect to finish revision and for the next stage to start + - Goal: revise the text of the proposal to reflect discussions during the + question stage +3. Objection stage + - Suggested span: 2 days + - Goal: identify unresolved issues that would cause harm to the team, + contributors, or the project + - Note: participants must clearly note whether each objection they raise is + considered paramount or non-paramount in their own estimation +4. Objection revision stage + - Suggested span: as long as it takes for the author and paramount objection + raisers to revise the proposal together. + - Goal: revise the proposal in collaboration with individual participants to + address and resolve paramount objections + - Note: if during this stage it is determined that the proposal cannot be + revised to address the paramount objection(s), then the proposal is tabled +5. Ratification + - Suggested span: N/A + - Goal: if there are no paramount objections during the objection stage, mark + the proposal as ratified and create issues to implement the proposal (if + needed) +6. Tabling + - Suggested span: N/A + - Goal: to end discussions for proposals that cannot be ratified, either due + to voluntary withdrawal of the proposal by the author or due to + insurmountable paramount objections + +## Proposal requirements + +Project proposals and technical implementation plans should follow the formats +outlined in [the documentation for those processes](./docs/projects/README.md). +All proposals should include a summary of the purpose of the proposal and the +problem(s) it attempts to address. + +## Stage descriptions + +## Additional practices + +The following additional conventions will help our team make expedient decisions +while still following the formalised process laid out above. + +### "Shortcutting" a round + +At any point during a round, any participant may say something along the lines +of "no (further) questions", "no reaction", or "no objection" in order to +short-cut their participation in the round. If all participants are finished +sharing their part in a given round, the author can choose to move to the next +round, even if the time period for the round has not been completed. This can be +particularly helpful for simpler discussions where the 2 business day +recommended time periods can feel overly slow. + +### Discussion Dashboard + +The +[discussion dashboard is implemented as a GitHub project](https://github.com/orgs/WordPress/projects/79/views/1) +for tracking the different stages of a proposal. Proposal authors are expected +to correctly add and update proposals as they move through the different stages +of discussion. This dashboard is used to +[help ensure we do not assign contributors to more than two discussions in parallel](#minimising-parallel-discussions), +so it is imperative that we maintain its accuracy. + +Each discussion should be tracked as a single card, with issues removed from the +"Pending proposal" column if a GitHub PR is opened. If a GitHub discussion is +used for the proposal, because those cannot be represented in GitHub project +boards, the issue should be used to track the status through the columns. + +This dashboard also serves as a record of decisions made on the team since the +dashboard's inception. Historical decisions that happened before the dashboard +started being used are not documented there. + +#### Column descriptions + +For the most part, the columns correspond 1-to-1 with stages of the Openverse +consent decision-making process. However, the following columns are unique and +bear explaining: + +- "Proposal requested": This column is meant for requested proposals or + discussions for which no formal proposal yet exists. This column should be + populated by the issues that document the request. +- "Discussion pending": This column is meant for proposals that have been + written, but cannot + +### Minimising parallel discussions + +#### Checking the dashboard + +Before requesting participation from specific people on a discussion, check the +[discussion dashboard](#discussion-dashboard) to ensure they're not already +involved in 2 ongoing discussions. If specific participants are required for a +given proposal (due to the relevance of their expertise in the proposal), then +you may open the proposal, but it should be left in the "pending discussion" +column. + +In addition to the general courtesy described in the previous section asking +authors to review the discussion dashboard before pinging individuals, we will +also want to have some practices to minimise team-wide process decisions. In +order to do this, we’ll need to triage discussions, in particular if a +retrospective brings up several important decisions that need to be made. In +those cases, if they’re truly decisions with team-wide implications, we can +follow two processes: + +1. Establish a team-wide discussion backlog and only allow one team-wide + discussion to occur at a time. Limiting this to 1 allows other non-team-wide + discussions to also happen at the same time without flooding the discussion + board with team-wide discussions and halting other, smaller, often technical + discussions. +2. Split the team into groups of three or four people who can participate in + different parts of the discussion. This is useful if there are multiple + time-sensitive discussions and could lead to synchronous “lightening process” + meetings to make faster decisions and reduce the ongoing discussion burden on + team members. Even in this case, limit to 1 ongoing team-wide process + discussion per team-member. + +For both, we will aim to limit the process discussions to one discussion at a +time for any given team member. This is recommended to avoid discussion burn out +as I think I’ve observed process discussions feeling much heavier weight and +burdensome than technical discussions. It also makes sure there is still room +for team members to be involved in one other separate technical discussion and +feel like they can still focus on their other work duties. + +### Current round call out + +The author must maintain a heading at the top of the PR description, discussion +question, or P2 post with the current round the discussion is in. This prevents +accidental back-sliding into already completed rounds or jumping ahead to rounds +not yet started. The call-out is embedded with the informational block linking +to the process documentation. This is maintained in addition to the process +described below in the "How to follow the process…" section where the author +will add a top-level comment introducing each new round when it starts. + +### Optional, synchronous "lightening process" + +If all the participants of a particular discussion are able to participate in a +synchronous version of the process outlined above, they may elect to do so. This +can be particularly useful for relatively small but impactful decisions where +the 2 business day periods would unnecessarily drag the process out. In these +cases, participants should hold a synchronous conversation with the +understanding that someone will take notes for each round, recording the +questions, reactions, and any objections that arise. **The notes should be +shared afterwards in the original proposal venue and should include explicit +headings per round.** If necessary, the synchronous discussion can be broken +into two separate sections to allow time for the revision round after reactions +are shared. + +Even in these cases, however, the proposal should still be written in a GitHub +PR or discussion. From 108cadd95ca87a0227ebb789ae15825eb8b580a3 Mon Sep 17 00:00:00 2001 From: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> Date: Fri, 10 Mar 2023 13:35:41 +1100 Subject: [PATCH 02/14] Move file to documentation website and expand --- CONSENT_DECISION_MAKING.md | 269 --------- .../reference/consent_decision_making.md | 553 ++++++++++++++++++ 2 files changed, 553 insertions(+), 269 deletions(-) delete mode 100644 CONSENT_DECISION_MAKING.md create mode 100644 documentation/reference/consent_decision_making.md diff --git a/CONSENT_DECISION_MAKING.md b/CONSENT_DECISION_MAKING.md deleted file mode 100644 index 91f0fa072c9..00000000000 --- a/CONSENT_DECISION_MAKING.md +++ /dev/null @@ -1,269 +0,0 @@ -# Consent decision-making - -The Openverse maintainers have elected to adopt a decision-making model based on -the -[Sociocracy practice of "consent decision-making"](https://patterns.sociocracy30.org/consent-decision-making.html). -We hope this will accomplish the following: - -- Bring expediency to decision-making by giving guidelines for how and what - types of feedback to give -- Adopt more specific standards about what types of feedback must be addressed - before a proposal can be ratified for implementation -- Give specificity in feedback expectations, both for who will participate in a - decision-making process and what responsibilities and tools they have for - participating -- Reaffirm trust between contributors when evaluating proposals - -Historically, each of these have presented problems for the Openverse project as -it has grown. Decision-making can drag on for months, proposal reviews get stuck -in feedback cycles over issues that could be addressed later on, and there were -few, if any, expectations around who would participate in a discussion or what -the expectations of that participation was. Adopting the process described -below, we hope, will address some of the underlying causes of these problems, in -addition to the benefits described above. - -The process described below is heavily modified from the regular Sociocratic -process. The differences come from two directions: - -- The needs of a largely asynchronously coordinated base of contributors -- Internal feedback and iteration on the initial process, even after - modification for asynchrony - -**This process is not set in stone.** Nor is it a set of laws that must be -followed at all times. This document uses prescriptive language filled with -imperatives primarily to prevent the process itself from being filled with -contingencies at every turn. However, as with every other aspect of our ever -evolving processes, these are merely suggestions that we expect contributors to -adhere to. They cannot cover every situation and undoubtedly there are -exceptional situations where following these suggestions to the letter would be -antithetical to the goals of the project and even of the process itself. - -If during your time as an Openverse contributor, you feel there are ways in -which this process can be improved and iterated upon, please know that this -process should be iterated upon and that suggestions for improvement are open -from any contributor to the project. - -## Terms - -- "Author": The person making the proposal. -- "Participants": All participants of the decision-making process, including the - author, the requested participants, and ad-hoc participants. -- "Reactions": A broad class of feedback that can include personal preferences - as well as general scepticisms about the validity or safety of the solutions - described in the proposal. -- "Question": A request for clarification or explanation of an aspect of the - proposal. Questions may also request additional information be added to the - proposal. -- "Objection": An explained uncertainty about the appropriateness, efficacy, or - safety of a solution -- "Paramount objection": An objection outlining an issue that would cause harm - to the project or its contributors; especially issues that could cause harm - and are difficult to reverse and not strictly necessary to accomplish the - goals of the project -- "Ratified proposal": A proposal that has undergone the formal decision-making - process and has been accepted as a valid solution for the problem it tries to - address by the participants of the discussion. -- "Process proposal": A proposal to change processes followed by the - contributors in the course of stewarding the project towards success. -- "Purpose": The motivation for the proposal. This often includes the problem - the proposal aims to solve. In the original Sociocratic model this is called - the "driver". - -## Major differences from the original process - -### Reactions - -Reactions can be shared at any time. Be careful to ensure that they're not -objections (which should, with few exceptions, be reserved for the objection -round). Examples of reactions are: - -- "I love this approach" -- "I like this proposal, but I don't understand X part of it yet" -- "I don't think this will work, but I left some questions to clarify the areas - I have concerns over" -- "I don't understand the underlying problem, so the solution seems too abstract - to me" -- "I don't think this solution will solve the problem as described" - -Note that these are not questions (they do not ask for clarification) nor are -they objections (they do not point to specific problems with the proposed -solution). - -### Removal of initial rounds - -Because our process is primarily asynchronous, because our decision-making -happens in public, and because the outcomes of our discussions are ultimately -documented in GitHub or other accessible venues, we can skip some of the initial -stages. Specifically, the "consent to driver" and the "present the proposal" -stages cannot work in the same way. Typically, the purpose of a proposal will -have been clarified through a previous discussion. Proposals raised without -prior "buy-in" from other contributors should be done so carefully, with the -understanding that participants may question the purpose and need for the -proposal. The presentation of a proposal happens implicitly when the GitHub PR -or discussion is opened to contain the proposal, so we do not need a special -step for this. - -## Process summary - -Full descriptions of each of these stages of discussion are below. This section -is meant as a summary for getting an initial overview for people new to the -process or refreshing the broad intentions for folks already familiar with it. - -These steps are ordered and must be followed in the order they are presented -here. - -1. Question stage - - Suggested span: 3 days - - Goal: clarify the proposal and uncover initial uncertainties or issues - - Note: at this point, participants may question the purpose of the proposal - if it was not previously agreed upon in a previous discussion. If the - proposal was requested as a product of an earlier discussion, then the - purpose was already agreed upon and should not itself come under question. -2. Revision stage - - There is no suggested time span, but the author should clearly note when - they expect to finish revision and for the next stage to start - - Goal: revise the text of the proposal to reflect discussions during the - question stage -3. Objection stage - - Suggested span: 2 days - - Goal: identify unresolved issues that would cause harm to the team, - contributors, or the project - - Note: participants must clearly note whether each objection they raise is - considered paramount or non-paramount in their own estimation -4. Objection revision stage - - Suggested span: as long as it takes for the author and paramount objection - raisers to revise the proposal together. - - Goal: revise the proposal in collaboration with individual participants to - address and resolve paramount objections - - Note: if during this stage it is determined that the proposal cannot be - revised to address the paramount objection(s), then the proposal is tabled -5. Ratification - - Suggested span: N/A - - Goal: if there are no paramount objections during the objection stage, mark - the proposal as ratified and create issues to implement the proposal (if - needed) -6. Tabling - - Suggested span: N/A - - Goal: to end discussions for proposals that cannot be ratified, either due - to voluntary withdrawal of the proposal by the author or due to - insurmountable paramount objections - -## Proposal requirements - -Project proposals and technical implementation plans should follow the formats -outlined in [the documentation for those processes](./docs/projects/README.md). -All proposals should include a summary of the purpose of the proposal and the -problem(s) it attempts to address. - -## Stage descriptions - -## Additional practices - -The following additional conventions will help our team make expedient decisions -while still following the formalised process laid out above. - -### "Shortcutting" a round - -At any point during a round, any participant may say something along the lines -of "no (further) questions", "no reaction", or "no objection" in order to -short-cut their participation in the round. If all participants are finished -sharing their part in a given round, the author can choose to move to the next -round, even if the time period for the round has not been completed. This can be -particularly helpful for simpler discussions where the 2 business day -recommended time periods can feel overly slow. - -### Discussion Dashboard - -The -[discussion dashboard is implemented as a GitHub project](https://github.com/orgs/WordPress/projects/79/views/1) -for tracking the different stages of a proposal. Proposal authors are expected -to correctly add and update proposals as they move through the different stages -of discussion. This dashboard is used to -[help ensure we do not assign contributors to more than two discussions in parallel](#minimising-parallel-discussions), -so it is imperative that we maintain its accuracy. - -Each discussion should be tracked as a single card, with issues removed from the -"Pending proposal" column if a GitHub PR is opened. If a GitHub discussion is -used for the proposal, because those cannot be represented in GitHub project -boards, the issue should be used to track the status through the columns. - -This dashboard also serves as a record of decisions made on the team since the -dashboard's inception. Historical decisions that happened before the dashboard -started being used are not documented there. - -#### Column descriptions - -For the most part, the columns correspond 1-to-1 with stages of the Openverse -consent decision-making process. However, the following columns are unique and -bear explaining: - -- "Proposal requested": This column is meant for requested proposals or - discussions for which no formal proposal yet exists. This column should be - populated by the issues that document the request. -- "Discussion pending": This column is meant for proposals that have been - written, but cannot - -### Minimising parallel discussions - -#### Checking the dashboard - -Before requesting participation from specific people on a discussion, check the -[discussion dashboard](#discussion-dashboard) to ensure they're not already -involved in 2 ongoing discussions. If specific participants are required for a -given proposal (due to the relevance of their expertise in the proposal), then -you may open the proposal, but it should be left in the "pending discussion" -column. - -In addition to the general courtesy described in the previous section asking -authors to review the discussion dashboard before pinging individuals, we will -also want to have some practices to minimise team-wide process decisions. In -order to do this, we’ll need to triage discussions, in particular if a -retrospective brings up several important decisions that need to be made. In -those cases, if they’re truly decisions with team-wide implications, we can -follow two processes: - -1. Establish a team-wide discussion backlog and only allow one team-wide - discussion to occur at a time. Limiting this to 1 allows other non-team-wide - discussions to also happen at the same time without flooding the discussion - board with team-wide discussions and halting other, smaller, often technical - discussions. -2. Split the team into groups of three or four people who can participate in - different parts of the discussion. This is useful if there are multiple - time-sensitive discussions and could lead to synchronous “lightening process” - meetings to make faster decisions and reduce the ongoing discussion burden on - team members. Even in this case, limit to 1 ongoing team-wide process - discussion per team-member. - -For both, we will aim to limit the process discussions to one discussion at a -time for any given team member. This is recommended to avoid discussion burn out -as I think I’ve observed process discussions feeling much heavier weight and -burdensome than technical discussions. It also makes sure there is still room -for team members to be involved in one other separate technical discussion and -feel like they can still focus on their other work duties. - -### Current round call out - -The author must maintain a heading at the top of the PR description, discussion -question, or P2 post with the current round the discussion is in. This prevents -accidental back-sliding into already completed rounds or jumping ahead to rounds -not yet started. The call-out is embedded with the informational block linking -to the process documentation. This is maintained in addition to the process -described below in the "How to follow the process…" section where the author -will add a top-level comment introducing each new round when it starts. - -### Optional, synchronous "lightening process" - -If all the participants of a particular discussion are able to participate in a -synchronous version of the process outlined above, they may elect to do so. This -can be particularly useful for relatively small but impactful decisions where -the 2 business day periods would unnecessarily drag the process out. In these -cases, participants should hold a synchronous conversation with the -understanding that someone will take notes for each round, recording the -questions, reactions, and any objections that arise. **The notes should be -shared afterwards in the original proposal venue and should include explicit -headings per round.** If necessary, the synchronous discussion can be broken -into two separate sections to allow time for the revision round after reactions -are shared. - -Even in these cases, however, the proposal should still be written in a GitHub -PR or discussion. diff --git a/documentation/reference/consent_decision_making.md b/documentation/reference/consent_decision_making.md new file mode 100644 index 00000000000..da598ccadf2 --- /dev/null +++ b/documentation/reference/consent_decision_making.md @@ -0,0 +1,553 @@ +# Consent decision-making + +The Openverse maintainers have elected to adopt a decision-making model based on +the +[Sociocracy practice of "consent decision-making"](https://patterns.sociocracy30.org/consent-decision-making.html). +We hope this will accomplish the following: + +- Bring expediency to decision-making by giving guidelines for how and what + types of feedback to give +- Adopt more specific standards about what types of feedback must be addressed + before a proposal can be ratified for implementation +- Give specificity in feedback expectations, both for who will participate in a + decision-making process and what responsibilities and tools they have for + participating +- Reaffirm trust between contributors when evaluating proposals + +Historically, each of these have presented problems for the Openverse project as +it has grown. Decision-making can drag on for months, proposal reviews get stuck +in feedback cycles over issues that could be addressed later on, and there were +few, if any, expectations around who would participate in a discussion or what +the expectations of that participation was. Adopting the process described +below, we hope, will address some of the underlying causes of these problems, in +addition to the benefits described above. + +The process described below is heavily modified from the regular Sociocratic +process. The differences come from two directions: + +- The needs of a largely asynchronously coordinated base of contributors +- Internal feedback and iteration on the initial process, even after + modification for asynchrony + +> ## When to follow this process +> +> Whether this process is followed for any given proposal or discussion is left +> entirely to the discretion of the people relevant to the discussion. We +> believe that this process helps the project's contributors make expedient and +> clear decisions. However, it should not become an obstacle that is followed +> for every tiny decision. If a decision can efficiently be made without this +> process, contributors are invited to do so. +> +> For the purposes of project planning, however, this process should be the +> default and should be the strong preference, keeping in mind that it can be +> made faster via [round shortcutting](#shortcutting-a-round) and the +> [synchronous lightening process](#optional-synchronous-lightening-process). + +## Continuous improvement and exceptions to every rule + +**This process is not set in stone.** Nor is it a set of laws that must be +followed at all times. This document uses prescriptive language filled with +imperatives primarily to prevent the process itself from being filled with +contingencies at every turn. However, as with every other aspect of our ever +evolving processes, these are merely suggestions that we expect contributors to +adhere to. They cannot cover every situation and undoubtedly there are +exceptional situations where following these suggestions to the letter would be +antithetical to the goals of the project and even of the process itself. + +If during your time as an Openverse contributor, you feel there are ways in +which this process can be improved and iterated upon, please know that this +process should be iterated upon and that suggestions for improvement are open +from any contributor to the project. + +## Terms + +- "Author": The person making the proposal. +- "Participants": All participants of the decision-making process, including the + author, the requested participants, and ad-hoc participants. +- "Reactions": A broad class of feedback that can include personal preferences + as well as general doubts about the validity or safety of the solutions + described in the proposal. +- "Question": A request for clarification or explanation of an aspect of the + proposal. Questions may also request additional information be added to the + proposal. +- "Objection": An explained uncertainty about the appropriateness, efficacy, or + safety of a solution +- "Paramount objection": An objection outlining an issue that would cause harm + to the project or its contributors; especially issues that could cause harm + and are difficult to reverse and not strictly necessary to accomplish the + goals of the project +- "Ratified proposal": A proposal that has undergone the formal decision-making + process and has been accepted as a valid solution for the problem it tries to + address by the participants of the discussion. +- "Process proposal": A proposal to change processes followed by the + contributors in the course of stewarding the project towards success. +- "Purpose": The motivation for the proposal. This is typically a statement + describing the problem the proposal aims to solve. In the original Sociocratic + model this is called the "driver". + +## Major differences from the original process + +Aside from being conducted primarily as an asynchronous process, Openverse's +consent decision-making process has the following major differences from the +Sociocratic model. + +### Reactions + +While the original process has a separate reactions round, in Openverse's +process, reactions can be shared at any time. Be careful to ensure that they're +not objections (which should, with few exceptions, be reserved for the objection +round). Examples of reactions are: + +- "I love this approach" +- "I like this proposal, but I don't understand X part of it yet" +- "I don't think this will work, but I left some questions to clarify the areas + I have concerns over" +- "I don't understand the underlying problem, so the solution seems too abstract + to me" +- "I don't think this solution will solve the problem as described" + +Note that these are not questions (they do not ask for clarification) nor are +they objections (they do not point to specific problems with the proposed +solution). + +### Removal of initial rounds + +Because our process is primarily asynchronous, because our decision-making +happens in public, and because the outcomes of our discussions are ultimately +documented in GitHub or other accessible venues, we can skip some of the initial +rounds. Specifically, the "consent to driver" and the "present the proposal" +rounds cannot work in the same way. Typically, the purpose of a proposal will +have been clarified through a previous discussion. Proposals raised without +prior "buy-in" from other contributors should be done so carefully, with the +understanding that participants may question the purpose and need for the +proposal. The presentation of a proposal happens implicitly when the GitHub PR +or discussion is opened to contain the proposal, so we do not need a special +step for this. + +## Process summary + +Full descriptions of each of these rounds of discussion are below. This section +is meant as a summary for getting an initial overview for people new to the +process or refreshing the broad intentions for folks already familiar with it. + +These steps are ordered and must be followed in the order they are presented +here. + +> **Nota bene**: The "goal" column is a very brief summary and is not intended +> to encapsulate the full scope of the round. Please refer to the +> [round descriptions below](#round-descriptions) for more details and examples. + +| round | Suggested span | Goal | +| ----------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------- | +| [Question round](#question-round) | 3 days | Clarify the proposal; share initial reactions | +| [Revision round](#revision-round) | Author's discretion | Update the text of the proposal to reflect the outcome of the previous round | +| [Objection round](#objection-round) | 2 days | Identify paramount and non-paramount objections | +| [Objection revision round](#objection-revision-round) | Author's discretion | Work with participants to revise the text of the proposal to address paramount objections | +| [Ratification](#ratification) | N/A | Mark as accepted and create issues to implement the proposal | +| [Tabling](#tabling) | N/A | Indicate that a proposal will not be implemented | + +## Proposal requirements + +Project proposals and technical implementation plans should follow the formats +outlined in [the documentation for those processes](./docs/projects/README.md). +All proposals should include a summary of the purpose of the proposal and the +problem(s) it attempts to address. + +Every proposal must include the following boilerplate text: + +```md +## Decision-making process + +For the purposes of this discussion, we will follow +[Openverse’s version of the Consent decision-making model](https://wordpress.github.io/openverse/reference/consent_decision_making.html). +Please note that this process follows formalised steps with specific +expectations of participants. Before jumping in, please read +[this document](https://wordpress.github.io/openverse/reference/consent_decision_making.html) +as well as +[Openverse’s Code of Conduct](https://github.com/WordPress/openverse/blob/main/CODE_OF_CONDUCT.md). +Please note that the consent decision-making document linked above also includes +specific provisions for opting out of a decision discussion you do not wish to +or cannot participate in. + +## Current round + +The discussion is currently in the {Question, Reaction, Revision, Objection +raising, Objection revision} round. +``` + +## Round descriptions + +Please keep in mind the following general guidelines that apply to all rounds: + +- Reactions may be shared at any of the "feedback" rounds (Question and + Objection). +- Proposal authors are not obligated to respond to every question, reaction, or + objection that is raised, except for paramount objections. While there is an + expectation that the author will address outstanding questions, it isn't + necessary to respond to every non-paramount objection before moving on to + subsequent rounds or ratifying the proposal. It is, of course, in the best + interest of the project and the proposal that as much clarity as possible is + achieved. +- Authors may table a proposal at any time at their discretion. If the proposal + is tabled, discussion should not be expected to continue, but may, if there is + something important being discussed. +- Any round with a suggested length of time is subject to + [shortcutting as described below](#shortcutting-a-round) or to extension at + the discretion of the participants. + +### Question round + +This round lasts for 3 business days after the discussion starts but can be +extended if questions reveal significant gaps in the proposal that must be +understood before the proposal can be revised in the revision step. These +questions are different from objections in that they’re not in the form of "we +cannot do this because x part of the proposal will not work". Rather, they are +clarifying questions in the form of: + +- "I don’t understand y in the proposal, can you clarify what is meant by this?" +- "I think a gap exists in the proposed solution here [clarify where]. Can you + fill in the details in this area?" + +In short, the goal of the question round is for everyone participating to fully +understand the proposal. Participants are urged that many objections can be +restated as questions. This helps promote good faith between participants and +allows the author to clarify things they might have missed in the initial draft +of the proposal. This does _not_ mean that known paramount objections should be +reserved by participants. If you know that a proposed solution is impossible or +illegal, please do raise this concern as soon as possible. + +Note that the author does not have to respond to every question. However, they +should keep them in mind during the revision round. + +#### Reactions + +This round also invites participants to share reactions, positive or negative, +separate from potential paramount objections and in particular is an excellent +venue to highlight positive aspects of the proposal regardless of whether +paramount objections might be raised later. You may also share non-paramount +objections at this round. For example, “I find JavaScript harder to work with +than Python” is an objection but not a paramount objection. What makes an +objection “paramount” is clarified further in the +[Objection round](#objection-round) below. + +Reactions are explicitly expected at this round because, similar to questions, +they can help prompt further clarification from the author to be address in the +revision round. + +#### Purpose + +Proposals should all include an explicit "purpose". Often these are informed by +the needs of a particular project associated with the proposal or with a +requested discussion as the result of a retrospective or other self-feedback +mechanism. However, contributors may, at their discretion, raise proposals for +discussion that do not have prior conversations. In these cases, the question +round is also understood to include an evaluation and clarification of the +purpose of the proposal. For regularly requested proposals, however, the purpose +is taken to be accepted and should not be the focus + +### Revision round + +At this round, the author has the opportunity to revise the proposal in response +to the questions and reactions raised. This round has no set time period. The +author should use their discretion and give an expected time when the revised +version will be ready. The expected date of completion for the revision is both +for accountability (to prevent projects from being stalled indefinitely) and for +clarity of expectations for the other participants in the process. If the author +requires additional time beyond their initial estimation, they should let the +other participants know as soon as possible, keeping in mind that other +discussions may be stalled in the meantime. + +To every extent possible, **no revisions should be made to the proposal before +this point other than grammatical or spelling corrections**. The reason for this +is to allow the question round to fully complete without the proposal changing +during the discussion. This allows clarification to happen fully without having +to track ongoing changes to the proposal and sets the expectation that changes +the proposal incorporate all the clarifying questions asked in addition to any +information surfaced in the reaction round. This helps to minimise the +potentially "frantic" nature of a discussion that is happening about a proposal +document that is changing simultaneously with the discussion. + +### Objection round + +This round lasts for 2 business days. Participants are now invited to share +“paramount objections” to the proposal, if any exist. Objections are considered +“paramount” only if: + +- They point to an issue that prevents the team from achieving its goals + (whether these are technical, community, or interpersonal). These issues can + also be said to "harm" the project or its contributors. +- The objection reveals something that is irreversible (or extremely difficult + to reverse) of which the participants are not at least “okay” with or “sure + of”. For example, a proposal to switch to using MySQL when we’re currently + invested heavily in Postgres would require significant time investment that + would be difficult to reverse. If the participants are not absolutely certain + that it is the best decision, then any objection to making the switch would be + paramount. + +Note that during this round, like the question round, the author should not +modify the text of the proposal. The focus of the author in this round should be +in clarifying objections (especially paramount objections) and deciding whether +it will be possible or reasonable to revise the proposal to address them. This +allows time for participants to fully digest the proposal and raise all +objections without further revision happening. Participants are expected to help +each other decide whether an objection is paramount. Whether an objection is +paramount can be questioned by the author, but they should prefer to defer to +the participants and trust their judgement. + +If there are no paramount objections then the process has finished and the +proposal is [ratified](#ratification). In that case mark the discussion as +ratified, however this can be best done with the tool being used (merge the PR, +close the discussion, etc). The author is responsible for updating the “Current +round” text to signify the proposal’s ratification. + +At the end of the 2-day period, if the author does not think they can address +the paramount objections, then the proposal is [tabled](#tabling). For projects +where we absolutely want to follow through on the idea, this should be rare. +However, sometimes a paramount objection may be raised that requires completely +re-writing the proposal from the ground up. In that case, we will follow this +process again from the start with the new proposal, so we will end the process +for the first proposal at this round and wait for a new one to be raised. In +these cases, the author should update the “Current round” text to note that was +tabled and that a new proposal has been requested. + +### Objection revision round + +This round, similar to the previous revision round, lasts as long as the author +of the proposal needs it to last to completely address the paramount objections. +The author should work with the person who raised the objection to revise the +proposal to address the issue to resolution. The goal of this round is to reach +a "good enough" middle ground solution that either completely addresses the +paramount objection or mitigates the potential harm identified. + +As stated in the previous round’s description, objection revision should only +happen if paramount objections can indeed be revised to remove the harm. If the +paramount objection involves a core issue of the proposal that cannot be +revised, then an entirely new proposal should be written, rather than the +"revision" replacing the entire existing proposal. It may be the case that in +the process of revision, the author of the proposal realises that they need to +"return to the drawing board". Please keep in mind that this is not a failure +and should be celebrated. So long as the objections were truly paramount, the +participants in the discussion and the author of the proposal have successfully +prevent long-term harm to the goals or people on the project. That is good news. + +Once the paramount objections are addressed, we will consider the proposal to be +accepted. The team as a whole can move on the next step of the project, whether +that is implementation planning or implementation itself. + +## Outcomes + +There are two possible outcomes for any proposal that follows this process: +ratification or tabling. All raised proposals should eventually be marked as +ratified (if the decision-making process warrants it) or tabled. + +### Ratification + +Ratification occurs once all paramount objections have been addressed and the +author is satisfied with the state of the proposal. At this point, if there are +issues to create to implement the proposal, they should be created and linked in +the proposal text relevant to the issue. + +### Tabling + +Tabling can occur in the following cases: + +- At any time, at the discretion of the author +- Before a proposal is written, if the team reneges on a requested discussion +- After a proposal is written, but before the discussion happens, if it is clear + the proposal will not fit the needs of the project +- During the objection round when insurmountable paramount objections are raised + +In the final case, the participants of the discussion are responsible for +deciding whether a new proposal should be requested. + +In any case, the proposal (if one exists) or the issue (if a proposal does not +exist) should be updated to reflect the tabled status and the reason why it was +tabled. It should also indicate whether a new proposal is requested. If a +proposal exists, the author is tasked with this responsibility. If no proposal +yet exists, then someone must volunteer to document the reasons for this +outcome. + +## Additional practices + +The following additional conventions will help our team make expedient decisions +while still following the formalised process laid out above. + +### "Shortcutting" a round + +At any point during a round, any participant may say something along the lines +of "no (further) questions", "no reaction", or "no objection" in order to +short-cut their participation in the round. If all participants are finished +sharing their part in a given round, the author can choose to move to the next +round, even if the time period for the round has not been completed. This can be +particularly helpful for simpler discussions where the 2 business day +recommended time periods can feel overly slow. + +### Discussion Dashboard + +The +[discussion dashboard is implemented as a GitHub project](https://github.com/orgs/WordPress/projects/79/views/1) +for tracking the different rounds of a proposal. Proposal authors are expected +to correctly add and update proposals as they move through the different rounds +of discussion. This dashboard is used to +[help ensure we do not assign contributors to more than two discussions in parallel](#minimising-parallel-discussions), +so it is imperative that we maintain its accuracy. + +Each discussion should be tracked as a single card, with issues removed from the +"Pending proposal" column if a GitHub PR is opened. If a GitHub discussion is +used for the proposal, because those cannot be represented in GitHub project +boards, the issue should be used to track the status through the columns. + +This dashboard also serves as a record of decisions made on the team since the +dashboard's inception. Historical decisions that happened before the dashboard +started being used are not documented there. + +#### Column descriptions + +For the most part, the columns correspond 1-to-1 with rounds of the Openverse +consent decision-making process. However, the following columns are unique and +bear explaining: + +- "Proposal requested": This column is meant for requested proposals or + discussions for which no formal proposal yet exists. This column should be + populated by the issues that document the request. +- "Discussion pending": This column is meant for proposals that have been + written, but cannot + +### Minimising parallel discussions + +#### Checking the dashboard + +Before requesting participation from specific people on a discussion, check the +[discussion dashboard](#discussion-dashboard) to ensure they're not already +involved in 2 ongoing discussions. If specific participants are required for a +given proposal (due to the relevance of their expertise in the proposal), then +you may open the proposal, but it should be left in the "pending discussion" +column. + +Tips for checking the dashboard and not accidentally over-encumbering people: + +- Check for discussions in the "pending discussion" column. If someone is + already assigned to discussions there, then know that any new discussions that + _must_ involve them will need to be triaged with the other discussion +- If a discussion could happen using the "lightening process", then you may be + able to pull people in who are waiting for a discussion to restart during the + revision round, even if they're already participating in the discussion + +In either case, it is still courteous to check with the individuals and make it +clear that they can push the discussion to someone else (provided they're not a +necessary subject-matter expert). + +#### Project level process discussions + +Because project level process discussions usually effect all maintainers and +sometimes other contributors, they naturally garner the expectation of +involvement from broader sets of people than technical discussions. In addition +to the guidelines above for general discussions, we need additional special +guidelines to ensure we do not become over encumbered with process discussions +specifically. In particular, retrospectives may give rise to several discussions +that need to happen at once. In these cases, and others where process +discussions begin to dominate the discussion backlog, we'll need to triage +discussions. If discussions truly need the involvement of the entire team, we +can follow two processes: + +1. Put (and prioritise) the discussions into the "proposal requested" column of + the discussion dashboard and only allow one team-wide discussion to occur at + a time. Limiting this to 1 allows other non-team-wide discussions to also + happen at the same time without flooding the discussion board with team-wide + discussions and halting other, smaller, often technical discussions. +2. Split the group into groups of three or four people who can participate in + different parts of the discussion. This is useful if there are multiple + time-sensitive discussions and could lead to synchronous "lightening process" + meetings to make faster decisions and reduce the ongoing discussion burden on + team members. Even in this case, limit to 1 ongoing team-wide process + discussion per group of contributors. This is less useful if everyone on the + team wishes to give input in the discussion, although people are free to + asynchronously give input before the fact. + +For both, we will aim to limit the process discussions to one discussion at a +time for any given team member. This is recommended to avoid discussion burn out +as I think I’ve observed process discussions feeling much heavier weight and +burdensome than technical discussions. It also makes sure there is still room +for team members to be involved in one other separate technical discussion and +feel like they can still focus on their other work duties. + +### Current round call out + +The author must maintain a heading at the top of the PR description or +discussion body with the current round the discussion is in. This prevents +accidental back-sliding into already completed rounds or jumping ahead to rounds +not yet started. The call-out is embedded with the informational block linking +to the process documentation. This is maintained in addition to the process +described below in the "How to follow the process…" section where the author +will add a top-level comment introducing each new round when it starts. + +### Optional, synchronous "lightening process" + +If all the participants of a particular discussion are able to participate in a +synchronous version of the process outlined above, they may elect to do so. This +can be particularly useful for relatively small but impactful decisions where +the 2 business day periods would unnecessarily drag the process out. In these +cases, participants should hold a synchronous conversation with the +understanding that someone will take notes for each round, recording the +questions, reactions, and any objections that arise. **The notes should be +shared afterwards in the original proposal venue and should include explicit +headings per round.** If necessary, the synchronous discussion can be broken +into two separate sections to allow time for the revision round after reactions +are shared. + +Even in these cases, however, the proposal should still be written in a GitHub +PR or discussion. + +Differences in structure + +## How to follow the process in different settings + +The team has agreed to use GitHub for all discussions, with links shared on the +[WordPress Make Openverse blog](https://make.wordpress.org/openverse/) to help +visibility for certain discussions. + +There are two tools in GitHub that can be used for conducting a discussion: PRs +and GitHub Discussions. We do not use GitHub issues because they do not allow +for threading. + +### PRs + +GitHub PRs are used for project proposals, implementation planning RFCs, and +other proposals that will be documented as Markdown files in the repository. + +GitHub PRs have the following ways of interacting with comments: + +- Inline comments on specific lines of text or code + - These allow opening "threads" and can be resolved +- General PR comments +- Review comments + +Each of these can serve their own purposes: + +- Inline comments + - These are perfect to supplement the question and objection rounds. If a + question is about a specific part of the proposal (rather than a more + general clarification), participants can leave the question directly on the + part in question. Similarly, paramount objections specific to one part of + the proposal can be left as inline comments attached to a review requesting + changes. +- General PR comments + - For questions or non-paramount objections raised regarding the proposal in + general or for the reaction round. + - In addition to the PR description, the author of the PR will also create a + new top-level PR comment when a new round starts. +- Review comments + - These should be used in the objection raising round. Leave an approving + review if you have no paramount objections or "request changes" if you have + a paramount objection. Attach inline comments as needed in either case. + +### GitHub Discussions + +Because the format is slightly more limited than PRs, we will have a top-level +comment per round created by the author. Responses from participants should be +contained within the thread for each round. However, paramount objections during +the Objection round, should be raised as individual threads. Still, the author +should still create a top-level comment closing the previous round and opening +the objection round. If the proposal goes into objection revision, the +discussion for addressing a given objection can happen in the accompanying +thread. From a337eb34cb700ff78065af2bd5a24283902e5e6e Mon Sep 17 00:00:00 2001 From: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> Date: Fri, 10 Mar 2023 13:45:56 +1100 Subject: [PATCH 03/14] Group additional practices more clearly --- .../reference/consent_decision_making.md | 65 ++++++++++++------- 1 file changed, 41 insertions(+), 24 deletions(-) diff --git a/documentation/reference/consent_decision_making.md b/documentation/reference/consent_decision_making.md index da598ccadf2..c47f6033046 100644 --- a/documentation/reference/consent_decision_making.md +++ b/documentation/reference/consent_decision_making.md @@ -153,7 +153,8 @@ outlined in [the documentation for those processes](./docs/projects/README.md). All proposals should include a summary of the purpose of the proposal and the problem(s) it attempts to address. -Every proposal must include the following boilerplate text: +Every proposal must include the following boilerplate text in the PR description +or at the top of the GitHub Discussion: ```md ## Decision-making process @@ -372,16 +373,6 @@ outcome. The following additional conventions will help our team make expedient decisions while still following the formalised process laid out above. -### "Shortcutting" a round - -At any point during a round, any participant may say something along the lines -of "no (further) questions", "no reaction", or "no objection" in order to -short-cut their participation in the round. If all participants are finished -sharing their part in a given round, the author can choose to move to the next -round, even if the time period for the round has not been completed. This can be -particularly helpful for simpler discussions where the 2 business day -recommended time periods can feel overly slow. - ### Discussion Dashboard The @@ -415,6 +406,12 @@ bear explaining: ### Minimising parallel discussions +In the past, Openverse maintainers have been prone to feeling overwhelmed or +over encumbered by too many ongoing discussions demanding their attention. The +following practices are meant to mitigate the chances of this happening by +creating tools and processes for keep the number of active discussions per +participant to 2 or fewer. + #### Checking the dashboard Before requesting participation from specific people on a discussion, check the @@ -471,17 +468,23 @@ burdensome than technical discussions. It also makes sure there is still room for team members to be involved in one other separate technical discussion and feel like they can still focus on their other work duties. -### Current round call out +### Speeding up decision-making -The author must maintain a heading at the top of the PR description or -discussion body with the current round the discussion is in. This prevents -accidental back-sliding into already completed rounds or jumping ahead to rounds -not yet started. The call-out is embedded with the informational block linking -to the process documentation. This is maintained in addition to the process -described below in the "How to follow the process…" section where the author -will add a top-level comment introducing each new round when it starts. +The base process should help the Openverse project make decisions more quickly +and effectively. However, the following additional practices are available to +help move things along at an even faster clip, if so desired. -### Optional, synchronous "lightening process" +#### "Shortcutting" a round + +At any point during a round, any participant may say something along the lines +of "no (further) questions", "no reaction", or "no objection" in order to +short-cut their participation in the round. If all participants are finished +sharing their part in a given round, the author can choose to move to the next +round, even if the time period for the round has not been completed. This can be +particularly helpful for simpler discussions where the 2 business day +recommended time periods can feel overly slow. + +#### Optional, synchronous "lightening process" If all the participants of a particular discussion are able to participate in a synchronous version of the process outlined above, they may elect to do so. This @@ -495,10 +498,24 @@ headings per round.** If necessary, the synchronous discussion can be broken into two separate sections to allow time for the revision round after reactions are shared. -Even in these cases, however, the proposal should still be written in a GitHub -PR or discussion. - -Differences in structure +Even in these cases, however, the text of the proposal should still be written +in a GitHub PR or discussion and available for all participants to read _before_ +the lightening process. + +Differences in structure for the "lightening process" from the asynchronous +process are as follows: + +- Rather than tying the question and reaction rounds together, they are separate + rounds. Therefore, the rounds are as follows: + 1. Question + 1. Reaction + 1. Revision + 1. Objection + 1. Objection revision +- Each round should have notes taken clearly documenting the questions, + reactions, objections, and discussions for each (as appropriate). Priority + should be given to questions and objections that require revising the + proposal. ## How to follow the process in different settings From 1b6ded87545e419d365e5eff321c1bf14c85ec87 Mon Sep 17 00:00:00 2001 From: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> Date: Tue, 14 Mar 2023 15:24:31 +1100 Subject: [PATCH 04/14] Apply suggestions from code review Co-authored-by: Zack Krida --- .../reference/consent_decision_making.md | 51 ++++++++----------- 1 file changed, 22 insertions(+), 29 deletions(-) diff --git a/documentation/reference/consent_decision_making.md b/documentation/reference/consent_decision_making.md index c47f6033046..55b0f7858b4 100644 --- a/documentation/reference/consent_decision_making.md +++ b/documentation/reference/consent_decision_making.md @@ -1,6 +1,6 @@ # Consent decision-making -The Openverse maintainers have elected to adopt a decision-making model based on +The Openverse project uses a decision-making model based on the [Sociocracy practice of "consent decision-making"](https://patterns.sociocracy30.org/consent-decision-making.html). We hope this will accomplish the following: @@ -25,7 +25,7 @@ addition to the benefits described above. The process described below is heavily modified from the regular Sociocratic process. The differences come from two directions: -- The needs of a largely asynchronously coordinated base of contributors +- The needs of an asynchronously coordinated base of contributors - Internal feedback and iteration on the initial process, even after modification for asynchrony @@ -67,9 +67,7 @@ from any contributor to the project. - "Reactions": A broad class of feedback that can include personal preferences as well as general doubts about the validity or safety of the solutions described in the proposal. -- "Question": A request for clarification or explanation of an aspect of the - proposal. Questions may also request additional information be added to the - proposal. +- "Question": A request for clarification, explanation, or additional information about an aspect of the proposal. - "Objection": An explained uncertainty about the appropriateness, efficacy, or safety of a solution - "Paramount objection": An objection outlining an issue that would cause harm @@ -77,8 +75,7 @@ from any contributor to the project. and are difficult to reverse and not strictly necessary to accomplish the goals of the project - "Ratified proposal": A proposal that has undergone the formal decision-making - process and has been accepted as a valid solution for the problem it tries to - address by the participants of the discussion. + process and has been accepted as a valid solution by the participants of the discussion. - "Process proposal": A proposal to change processes followed by the contributors in the course of stewarding the project towards success. - "Purpose": The motivation for the proposal. This is typically a statement @@ -160,25 +157,25 @@ or at the top of the GitHub Discussion: ## Decision-making process For the purposes of this discussion, we will follow -[Openverse’s version of the Consent decision-making model](https://wordpress.github.io/openverse/reference/consent_decision_making.html). +[Openverse’s decision-making model](https://wordpress.github.io/openverse/reference/consent_decision_making.html). Please note that this process follows formalised steps with specific -expectations of participants. Before jumping in, please read +expectations of participants. Before contributing, please read [this document](https://wordpress.github.io/openverse/reference/consent_decision_making.html) as well as [Openverse’s Code of Conduct](https://github.com/WordPress/openverse/blob/main/CODE_OF_CONDUCT.md). Please note that the consent decision-making document linked above also includes -specific provisions for opting out of a decision discussion you do not wish to +instructions for opting out of a decision discussion you do not wish to or cannot participate in. ## Current round -The discussion is currently in the {Question, Reaction, Revision, Objection -raising, Objection revision} round. +The discussion is currently in the **{Question, Reaction, Revision, Objection +raising, Objection revision}** round. ``` ## Round descriptions -Please keep in mind the following general guidelines that apply to all rounds: +The following general guidelines apply to all rounds: - Reactions may be shared at any of the "feedback" rounds (Question and Objection). @@ -223,15 +220,15 @@ should keep them in mind during the revision round. #### Reactions This round also invites participants to share reactions, positive or negative, -separate from potential paramount objections and in particular is an excellent -venue to highlight positive aspects of the proposal regardless of whether -paramount objections might be raised later. You may also share non-paramount +separate from potential paramount objections. This is an excellent round +to highlight positive aspects of the proposal, regardless of any paramount +objections. You may also share non-paramount objections at this round. For example, “I find JavaScript harder to work with than Python” is an objection but not a paramount objection. What makes an objection “paramount” is clarified further in the [Objection round](#objection-round) below. -Reactions are explicitly expected at this round because, similar to questions, +Reactions are expected during this round because, similar to questions, they can help prompt further clarification from the author to be address in the revision round. @@ -258,7 +255,7 @@ requires additional time beyond their initial estimation, they should let the other participants know as soon as possible, keeping in mind that other discussions may be stalled in the meantime. -To every extent possible, **no revisions should be made to the proposal before +**No revisions should be made to the proposal before this point other than grammatical or spelling corrections**. The reason for this is to allow the question round to fully complete without the proposal changing during the discussion. This allows clarification to happen fully without having @@ -287,8 +284,8 @@ This round lasts for 2 business days. Participants are now invited to share Note that during this round, like the question round, the author should not modify the text of the proposal. The focus of the author in this round should be -in clarifying objections (especially paramount objections) and deciding whether -it will be possible or reasonable to revise the proposal to address them. This +to clarify objections (especially paramount objections) and decide whether +the proposal can address them. This allows time for participants to fully digest the proposal and raise all objections without further revision happening. Participants are expected to help each other decide whether an objection is paramount. Whether an objection is @@ -301,15 +298,14 @@ ratified, however this can be best done with the tool being used (merge the PR, close the discussion, etc). The author is responsible for updating the “Current round” text to signify the proposal’s ratification. -At the end of the 2-day period, if the author does not think they can address +After the 2-day period, if the author does not think they can address the paramount objections, then the proposal is [tabled](#tabling). For projects -where we absolutely want to follow through on the idea, this should be rare. +where we absolutely want to implement, this should be rare. However, sometimes a paramount objection may be raised that requires completely re-writing the proposal from the ground up. In that case, we will follow this process again from the start with the new proposal, so we will end the process for the first proposal at this round and wait for a new one to be raised. In -these cases, the author should update the “Current round” text to note that was -tabled and that a new proposal has been requested. +these cases, the author should update the “Current round” text to note that the proposal was tabled and that a new proposal has been requested. ### Objection revision round @@ -338,15 +334,12 @@ that is implementation planning or implementation itself. ## Outcomes There are two possible outcomes for any proposal that follows this process: -ratification or tabling. All raised proposals should eventually be marked as -ratified (if the decision-making process warrants it) or tabled. +ratification or tabling. ### Ratification Ratification occurs once all paramount objections have been addressed and the -author is satisfied with the state of the proposal. At this point, if there are -issues to create to implement the proposal, they should be created and linked in -the proposal text relevant to the issue. +author is satisfied with the state of the proposal. At this point any necessary GitHub issues should be created and linked to the proposal. ### Tabling From 5e78fe818e8564c993f6dfe7dc2a12d62b3b0658 Mon Sep 17 00:00:00 2001 From: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> Date: Tue, 14 Mar 2023 15:26:13 +1100 Subject: [PATCH 05/14] Update documentation/reference/consent_decision_making.md --- documentation/reference/consent_decision_making.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/reference/consent_decision_making.md b/documentation/reference/consent_decision_making.md index 55b0f7858b4..216df7fae8a 100644 --- a/documentation/reference/consent_decision_making.md +++ b/documentation/reference/consent_decision_making.md @@ -7,7 +7,7 @@ We hope this will accomplish the following: - Bring expediency to decision-making by giving guidelines for how and what types of feedback to give -- Adopt more specific standards about what types of feedback must be addressed +- Clarify the types of feedback expected during the decsion-making process, including which types of feedback must be addressed and which are marginal before a proposal can be ratified for implementation - Give specificity in feedback expectations, both for who will participate in a decision-making process and what responsibilities and tools they have for From 0357a88f71c4511455a682f1938a376f50d03952 Mon Sep 17 00:00:00 2001 From: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> Date: Tue, 14 Mar 2023 15:54:43 +1100 Subject: [PATCH 06/14] Proofread, clarify, and move sections a bit --- .../reference/consent_decision_making.md | 297 +++++++++--------- 1 file changed, 155 insertions(+), 142 deletions(-) diff --git a/documentation/reference/consent_decision_making.md b/documentation/reference/consent_decision_making.md index 216df7fae8a..e4d25c60c61 100644 --- a/documentation/reference/consent_decision_making.md +++ b/documentation/reference/consent_decision_making.md @@ -1,14 +1,18 @@ # Consent decision-making -The Openverse project uses a decision-making model based on -the +```{contents} Table of Contents +:depth: 3 +``` + +The Openverse project uses a decision-making model based on the [Sociocracy practice of "consent decision-making"](https://patterns.sociocracy30.org/consent-decision-making.html). We hope this will accomplish the following: - Bring expediency to decision-making by giving guidelines for how and what types of feedback to give -- Clarify the types of feedback expected during the decsion-making process, including which types of feedback must be addressed and which are marginal - before a proposal can be ratified for implementation +- Clarify the types of feedback expected during the decision-making process, + including which types of feedback must be addressed and which are marginal + before a proposal can be approved for implementation - Give specificity in feedback expectations, both for who will participate in a decision-making process and what responsibilities and tools they have for participating @@ -54,10 +58,8 @@ adhere to. They cannot cover every situation and undoubtedly there are exceptional situations where following these suggestions to the letter would be antithetical to the goals of the project and even of the process itself. -If during your time as an Openverse contributor, you feel there are ways in -which this process can be improved and iterated upon, please know that this -process should be iterated upon and that suggestions for improvement are open -from any contributor to the project. +If you have ideas for improving the Openverse decision-making process, please +share them. Suggestions are open to any contributor. ## Terms @@ -67,71 +69,36 @@ from any contributor to the project. - "Reactions": A broad class of feedback that can include personal preferences as well as general doubts about the validity or safety of the solutions described in the proposal. -- "Question": A request for clarification, explanation, or additional information about an aspect of the proposal. +- "Question": A request for clarification, explanation, or additional + information about an aspect of the proposal. - "Objection": An explained uncertainty about the appropriateness, efficacy, or safety of a solution - "Paramount objection": An objection outlining an issue that would cause harm to the project or its contributors; especially issues that could cause harm and are difficult to reverse and not strictly necessary to accomplish the goals of the project -- "Ratified proposal": A proposal that has undergone the formal decision-making - process and has been accepted as a valid solution by the participants of the discussion. +- "Approved proposal": A proposal that has undergone the formal decision-making + process and has been accepted as a valid solution by the participants of the + discussion. - "Process proposal": A proposal to change processes followed by the contributors in the course of stewarding the project towards success. - "Purpose": The motivation for the proposal. This is typically a statement describing the problem the proposal aims to solve. In the original Sociocratic model this is called the "driver". -## Major differences from the original process - -Aside from being conducted primarily as an asynchronous process, Openverse's -consent decision-making process has the following major differences from the -Sociocratic model. - -### Reactions - -While the original process has a separate reactions round, in Openverse's -process, reactions can be shared at any time. Be careful to ensure that they're -not objections (which should, with few exceptions, be reserved for the objection -round). Examples of reactions are: - -- "I love this approach" -- "I like this proposal, but I don't understand X part of it yet" -- "I don't think this will work, but I left some questions to clarify the areas - I have concerns over" -- "I don't understand the underlying problem, so the solution seems too abstract - to me" -- "I don't think this solution will solve the problem as described" - -Note that these are not questions (they do not ask for clarification) nor are -they objections (they do not point to specific problems with the proposed -solution). - -### Removal of initial rounds - -Because our process is primarily asynchronous, because our decision-making -happens in public, and because the outcomes of our discussions are ultimately -documented in GitHub or other accessible venues, we can skip some of the initial -rounds. Specifically, the "consent to driver" and the "present the proposal" -rounds cannot work in the same way. Typically, the purpose of a proposal will -have been clarified through a previous discussion. Proposals raised without -prior "buy-in" from other contributors should be done so carefully, with the -understanding that participants may question the purpose and need for the -proposal. The presentation of a proposal happens implicitly when the GitHub PR -or discussion is opened to contain the proposal, so we do not need a special -step for this. - ## Process summary -Full descriptions of each of these rounds of discussion are below. This section -is meant as a summary for getting an initial overview for people new to the -process or refreshing the broad intentions for folks already familiar with it. +The process breaks proposal evaluation and decision-making into a series of +rounds. Each round has expectations about what kinds of feedback are +appropriate. These steps are ordered and must be followed in the order they are +presented here. -These steps are ordered and must be followed in the order they are presented -here. +Full descriptions for each of these rounds are below. This section is a summary +meant to give an overview for people new to or refreshing themselves on the +process. -> **Nota bene**: The "goal" column is a very brief summary and is not intended -> to encapsulate the full scope of the round. Please refer to the +> **Note** The "goal" column is a very brief summary and is not intended to +> encapsulate the full scope of the round. Please refer to the > [round descriptions below](#round-descriptions) for more details and examples. | round | Suggested span | Goal | @@ -140,7 +107,7 @@ here. | [Revision round](#revision-round) | Author's discretion | Update the text of the proposal to reflect the outcome of the previous round | | [Objection round](#objection-round) | 2 days | Identify paramount and non-paramount objections | | [Objection revision round](#objection-revision-round) | Author's discretion | Work with participants to revise the text of the proposal to address paramount objections | -| [Ratification](#ratification) | N/A | Mark as accepted and create issues to implement the proposal | +| [Approval](#approval) | N/A | Mark as approved and create issues to implement the proposal | | [Tabling](#tabling) | N/A | Indicate that a proposal will not be implemented | ## Proposal requirements @@ -157,15 +124,14 @@ or at the top of the GitHub Discussion: ## Decision-making process For the purposes of this discussion, we will follow -[Openverse’s decision-making model](https://wordpress.github.io/openverse/reference/consent_decision_making.html). -Please note that this process follows formalised steps with specific -expectations of participants. Before contributing, please read +[Openverse's decision-making model](https://wordpress.github.io/openverse/reference/consent_decision_making.html). +This process follows formalised steps with specific expectations of +participants. Before contributing, please read [this document](https://wordpress.github.io/openverse/reference/consent_decision_making.html) as well as -[Openverse’s Code of Conduct](https://github.com/WordPress/openverse/blob/main/CODE_OF_CONDUCT.md). -Please note that the consent decision-making document linked above also includes -instructions for opting out of a decision discussion you do not wish to -or cannot participate in. +[Openverse's Code of Conduct](https://github.com/WordPress/openverse/blob/main/CODE_OF_CONDUCT.md). +The consent decision-making document linked above also includes instructions for +opting out of a decision discussion you do not wish to or cannot participate in. ## Current round @@ -195,53 +161,54 @@ The following general guidelines apply to all rounds: ### Question round -This round lasts for 3 business days after the discussion starts but can be -extended if questions reveal significant gaps in the proposal that must be -understood before the proposal can be revised in the revision step. These -questions are different from objections in that they’re not in the form of "we -cannot do this because x part of the proposal will not work". Rather, they are -clarifying questions in the form of: +The goal of the question round is for everyone participating to fully understand +the proposal. -- "I don’t understand y in the proposal, can you clarify what is meant by this?" +The round lasts for 3 business days but can be extended if important gaps in the +proposal are found that would delay revision. Questions are different from +objections in that they're not in the form of "we cannot do this because x part +of the proposal will not work". Rather, they are clarifying questions in the +form of: + +- "I don't understand y in the proposal, can you clarify what is meant by this?" - "I think a gap exists in the proposed solution here [clarify where]. Can you fill in the details in this area?" -In short, the goal of the question round is for everyone participating to fully -understand the proposal. Participants are urged that many objections can be -restated as questions. This helps promote good faith between participants and -allows the author to clarify things they might have missed in the initial draft -of the proposal. This does _not_ mean that known paramount objections should be -reserved by participants. If you know that a proposed solution is impossible or -illegal, please do raise this concern as soon as possible. +Participants should keep in mind that many objections can be restated as +questions. This helps promote good faith between participants and allows the +author to clarify things they might have missed in the initial draft of the +proposal. This does _not_ mean participants should delay sharing known paramount +objections. If you know that a proposed solution is impossible or illegal, +please do raise this concern as soon as possible. -Note that the author does not have to respond to every question. However, they -should keep them in mind during the revision round. +Note that the author does not have to respond to _every_ question. However, they +should keep them in mind during the revision round with the understanding that +the questions are shared in order to clarify the proposal. #### Reactions This round also invites participants to share reactions, positive or negative, -separate from potential paramount objections. This is an excellent round -to highlight positive aspects of the proposal, regardless of any paramount -objections. You may also share non-paramount -objections at this round. For example, “I find JavaScript harder to work with -than Python” is an objection but not a paramount objection. What makes an -objection “paramount” is clarified further in the -[Objection round](#objection-round) below. - -Reactions are expected during this round because, similar to questions, -they can help prompt further clarification from the author to be address in the -revision round. +separate from potential paramount objections. This is an excellent round to +highlight positive aspects of the proposal, regardless of any paramount +objections. You may also share non-paramount objections at this round. For +example, "I find JavaScript harder to work with than Python" is an objection but +not a paramount objection. What makes an objection "paramount" is clarified +further in the [Objection round](#objection-round) below. + +Reactions are expected during this round because, similar to questions, they can +help prompt further clarification from the author to be address in the revision +round. #### Purpose -Proposals should all include an explicit "purpose". Often these are informed by +Proposals must all include an explicit "purpose". Often these are informed by the needs of a particular project associated with the proposal or with a requested discussion as the result of a retrospective or other self-feedback mechanism. However, contributors may, at their discretion, raise proposals for discussion that do not have prior conversations. In these cases, the question round is also understood to include an evaluation and clarification of the purpose of the proposal. For regularly requested proposals, however, the purpose -is taken to be accepted and should not be the focus +is taken to be accepted and should not be the focus of the discussion. ### Revision round @@ -255,68 +222,66 @@ requires additional time beyond their initial estimation, they should let the other participants know as soon as possible, keeping in mind that other discussions may be stalled in the meantime. -**No revisions should be made to the proposal before -this point other than grammatical or spelling corrections**. The reason for this -is to allow the question round to fully complete without the proposal changing -during the discussion. This allows clarification to happen fully without having -to track ongoing changes to the proposal and sets the expectation that changes -the proposal incorporate all the clarifying questions asked in addition to any -information surfaced in the reaction round. This helps to minimise the -potentially "frantic" nature of a discussion that is happening about a proposal -document that is changing simultaneously with the discussion. +**No revisions should be made to the proposal before this point other than +grammatical or spelling corrections**. The reason for this is to allow the +question round to fully complete without the proposal changing during the +discussion. This allows clarification to happen fully without having to track +ongoing changes to the proposal. It also sets the expectation that revisions to +the proposal address the questions and reactions in full. This helps to minimise +the potentially "frantic" nature of a discussion that is happening about a +proposal document that is changing simultaneously with the discussion. ### Objection round This round lasts for 2 business days. Participants are now invited to share -“paramount objections” to the proposal, if any exist. Objections are considered -“paramount” only if: +"paramount objections" to the proposal, if any exist. Objections are considered +"paramount" only if: - They point to an issue that prevents the team from achieving its goals (whether these are technical, community, or interpersonal). These issues can also be said to "harm" the project or its contributors. - The objection reveals something that is irreversible (or extremely difficult - to reverse) of which the participants are not at least “okay” with or “sure - of”. For example, a proposal to switch to using MySQL when we’re currently + to reverse) of which the participants are not at least "okay" with or "sure + of". For example, a proposal to switch to using MySQL when we're currently invested heavily in Postgres would require significant time investment that would be difficult to reverse. If the participants are not absolutely certain that it is the best decision, then any objection to making the switch would be paramount. -Note that during this round, like the question round, the author should not -modify the text of the proposal. The focus of the author in this round should be -to clarify objections (especially paramount objections) and decide whether -the proposal can address them. This -allows time for participants to fully digest the proposal and raise all -objections without further revision happening. Participants are expected to help -each other decide whether an objection is paramount. Whether an objection is -paramount can be questioned by the author, but they should prefer to defer to -the participants and trust their judgement. +During this round, as in the question round, the author should not modify the +text of the proposal. The focus of the author in this round should be to clarify +objections (especially paramount objections) and decide whether the proposal can +address them. This allows time for participants to fully digest the proposal and +raise all objections without further revision happening. Participants are +expected to help each other decide whether an objection is paramount. Whether an +objection is paramount can be questioned by the author, but they should prefer +to defer to the participants and trust their judgement. If there are no paramount objections then the process has finished and the -proposal is [ratified](#ratification). In that case mark the discussion as -ratified, however this can be best done with the tool being used (merge the PR, -close the discussion, etc). The author is responsible for updating the “Current -round” text to signify the proposal’s ratification. - -After the 2-day period, if the author does not think they can address -the paramount objections, then the proposal is [tabled](#tabling). For projects -where we absolutely want to implement, this should be rare. -However, sometimes a paramount objection may be raised that requires completely -re-writing the proposal from the ground up. In that case, we will follow this -process again from the start with the new proposal, so we will end the process -for the first proposal at this round and wait for a new one to be raised. In -these cases, the author should update the “Current round” text to note that the proposal was tabled and that a new proposal has been requested. +proposal is [approved](#approval). + +After the 2-day period, if the author does not think they can address the +paramount objections, then the proposal is [tabled](#tabling). For certain +proposals, this will be an unlikely outcome, in particular if the purpose of the +proposal is well-established and necessary for the project. However, sometimes a +paramount objection may be raised that requires completely re-writing the +proposal from the ground up. In that case, we will follow this process again +from the start with the new proposal, so we will end the process for the first +proposal at this round and wait for a new one to be raised. + +Regardless of the outcome, the author is responsible for completing +[the steps to finalise the discussion](#outcomes). ### Objection revision round This round, similar to the previous revision round, lasts as long as the author -of the proposal needs it to last to completely address the paramount objections. -The author should work with the person who raised the objection to revise the -proposal to address the issue to resolution. The goal of this round is to reach -a "good enough" middle ground solution that either completely addresses the -paramount objection or mitigates the potential harm identified. +needs to completely address the paramount objections. The author will work with +the person who raised the objection to revise the proposal to address the issue +to resolution. The goal of this round is to reach a "good enough" middle ground +solution that either completely addresses the paramount objection or mitigates +the potential harm identified. -As stated in the previous round’s description, objection revision should only +As stated in the previous round's description, objection revision should only happen if paramount objections can indeed be revised to remove the harm. If the paramount objection involves a core issue of the proposal that cannot be revised, then an entirely new proposal should be written, rather than the @@ -334,12 +299,20 @@ that is implementation planning or implementation itself. ## Outcomes There are two possible outcomes for any proposal that follows this process: -ratification or tabling. +approval or tabling. In both cases, the author is expected to: + +- Update the current round callout to indicate the outcome +- If the proposal is in a GitHub discussion, lock the discussion +- If the proposal is in a PR, merge the PR if approved or close it if tabled +- Move the associated card on the discussion dashboard to the appropriate column -### Ratification +Further requirements specific to each outcome follow. -Ratification occurs once all paramount objections have been addressed and the -author is satisfied with the state of the proposal. At this point any necessary GitHub issues should be created and linked to the proposal. +### Approval + +Approval occurs once all paramount objections have been addressed and the author +is satisfied with the state of the proposal. At this point any necessary GitHub +issues should be created and linked to the proposal. ### Tabling @@ -389,13 +362,14 @@ started being used are not documented there. For the most part, the columns correspond 1-to-1 with rounds of the Openverse consent decision-making process. However, the following columns are unique and -bear explaining: +bear explanation: - "Proposal requested": This column is meant for requested proposals or discussions for which no formal proposal yet exists. This column should be populated by the issues that document the request. - "Discussion pending": This column is meant for proposals that have been - written, but cannot + written, but cannot yet start the decision-making process (likely due to + contributor unavailability). ### Minimising parallel discussions @@ -456,7 +430,7 @@ can follow two processes: For both, we will aim to limit the process discussions to one discussion at a time for any given team member. This is recommended to avoid discussion burn out -as I think I’ve observed process discussions feeling much heavier weight and +as I think I've observed process discussions feeling much heavier weight and burdensome than technical discussions. It also makes sure there is still room for team members to be involved in one other separate technical discussion and feel like they can still focus on their other work duties. @@ -561,3 +535,42 @@ should still create a top-level comment closing the previous round and opening the objection round. If the proposal goes into objection revision, the discussion for addressing a given objection can happen in the accompanying thread. + +## Major differences from the original process + +Aside from being conducted primarily as an asynchronous process, Openverse's +consent decision-making process has the following major differences from the +Sociocratic model. + +### Reactions + +While the original process has a separate reactions round, in Openverse's +process, reactions can be shared at any time. Be careful to ensure that they're +not objections (which should, with few exceptions, be reserved for the objection +round). Examples of reactions are: + +- "I love this approach" +- "I like this proposal, but I don't understand X part of it yet" +- "I don't think this will work, but I left some questions to clarify the areas + I have concerns over" +- "I don't understand the underlying problem, so the solution seems too abstract + to me" +- "I don't think this solution will solve the problem as described" + +Note that these are not questions (they do not ask for clarification) nor are +they objections (they do not point to specific problems with the proposed +solution). + +### Removal of initial rounds + +Because our process is primarily asynchronous, because our decision-making +happens in public, and because the outcomes of our discussions are ultimately +documented in GitHub or other accessible venues, we can skip some of the initial +rounds. Specifically, the "consent to driver" and the "present the proposal" +rounds cannot work in the same way. Typically, the purpose of a proposal will +have been clarified through a previous discussion. Proposals raised without +prior "buy-in" from other contributors should be done so carefully, with the +understanding that participants may question the purpose and need for the +proposal. The presentation of a proposal happens implicitly when the GitHub PR +or discussion is opened to contain the proposal, so we do not need a special +step for this. From 8494240765fa25d022ccfe87ce6eeb1333a2afa5 Mon Sep 17 00:00:00 2001 From: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> Date: Tue, 14 Mar 2023 16:09:43 +1100 Subject: [PATCH 07/14] Remove redundant TOC (sidebar already has it) --- documentation/reference/consent_decision_making.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/documentation/reference/consent_decision_making.md b/documentation/reference/consent_decision_making.md index e4d25c60c61..9bb1bc67e9d 100644 --- a/documentation/reference/consent_decision_making.md +++ b/documentation/reference/consent_decision_making.md @@ -1,9 +1,5 @@ # Consent decision-making -```{contents} Table of Contents -:depth: 3 -``` - The Openverse project uses a decision-making model based on the [Sociocracy practice of "consent decision-making"](https://patterns.sociocracy30.org/consent-decision-making.html). We hope this will accomplish the following: From 76b6a24e56553ae5c0f90e708b7be3fb37036179 Mon Sep 17 00:00:00 2001 From: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> Date: Wed, 15 Mar 2023 09:31:55 +1100 Subject: [PATCH 08/14] Clarify qualifications passage --- .../reference/consent_decision_making.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/documentation/reference/consent_decision_making.md b/documentation/reference/consent_decision_making.md index 9bb1bc67e9d..4b34c80f15e 100644 --- a/documentation/reference/consent_decision_making.md +++ b/documentation/reference/consent_decision_making.md @@ -46,16 +46,19 @@ process. The differences come from two directions: ## Continuous improvement and exceptions to every rule **This process is not set in stone.** Nor is it a set of laws that must be -followed at all times. This document uses prescriptive language filled with -imperatives primarily to prevent the process itself from being filled with -contingencies at every turn. However, as with every other aspect of our ever -evolving processes, these are merely suggestions that we expect contributors to -adhere to. They cannot cover every situation and undoubtedly there are -exceptional situations where following these suggestions to the letter would be -antithetical to the goals of the project and even of the process itself. +followed at all times. This document uses prescriptive language. However, keep +in mind that broad qualifications exist and are described in this section. The +document avoids qualifying every imperative in order to prevent the text from +ballooning in size and complexity. + +As with every other aspect of our ever evolving processes, this process is +merely a guideline that we expect contributors to adhere to. It cannot cover +every situation and undoubtedly there are exceptional situations where following +the process to the letter would be antithetical to the goals of the project and +even of the process itself. If you have ideas for improving the Openverse decision-making process, please -share them. Suggestions are open to any contributor. +share them. Any contributor may provide feedback on this process. ## Terms From c057d4531aae054c97a7e7d139fdd6858f616ffb Mon Sep 17 00:00:00 2001 From: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> Date: Fri, 17 Mar 2023 19:06:53 +1100 Subject: [PATCH 09/14] Remove reaction round from rounds list in call-out --- documentation/reference/consent_decision_making.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentation/reference/consent_decision_making.md b/documentation/reference/consent_decision_making.md index 4b34c80f15e..8985f1d7ce7 100644 --- a/documentation/reference/consent_decision_making.md +++ b/documentation/reference/consent_decision_making.md @@ -134,8 +134,7 @@ opting out of a decision discussion you do not wish to or cannot participate in. ## Current round -The discussion is currently in the **{Question, Reaction, Revision, Objection -raising, Objection revision}** round. +The discussion is currently in the **{Question, Revision, Objection, Objection revision}** round. ``` ## Round descriptions From 090afd6e4224efceeb417dd7207276f27071925f Mon Sep 17 00:00:00 2001 From: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> Date: Fri, 24 Mar 2023 12:49:22 +1100 Subject: [PATCH 10/14] WIP diagram/revision --- documentation/Pipfile | 2 + documentation/Pipfile.lock | 251 +++++++++--------- documentation/conf.py | 2 +- .../reference/consent_decision_making.md | 192 +++++++------- documentation/reference/index.md | 1 + 5 files changed, 226 insertions(+), 222 deletions(-) diff --git a/documentation/Pipfile b/documentation/Pipfile index ae584424536..7f4c6fe97e2 100644 --- a/documentation/Pipfile +++ b/documentation/Pipfile @@ -4,12 +4,14 @@ verify_ssl = true name = "pypi" [packages] +sphinxcontrib-mermaid = "*" [dev-packages] sphinx = "*" sphinx-autobuild = "*" furo = "*" myst-parser = "*" +sphinxcontrib-mermaid = "*" [requires] python_version = "3.10" diff --git a/documentation/Pipfile.lock b/documentation/Pipfile.lock index 1040a77ad54..8cb0f2af66e 100644 --- a/documentation/Pipfile.lock +++ b/documentation/Pipfile.lock @@ -1,7 +1,7 @@ { "_meta": { "hash": { - "sha256": "08f2f2ccaf2dc674900f40a9d58969523460d490e3f20ea95598e4e9cfce86e7" + "sha256": "3f5f4c537fce3734eaae2570f6aaa43fe974d79624e708232e21163b34ac9f64" }, "pipfile-spec": 6, "requires": { @@ -15,132 +15,129 @@ } ] }, - "default": {}, + "default": { + "sphinxcontrib-mermaid": { + "hashes": [ + "sha256:15491c24ec78cf1626b1e79e797a9ce87cb7959cf38f955eb72dd5512aeb6ce9", + "sha256:fa3e5325d4ba395336e6137d113f55026b1a03ccd115dc54113d1d871a580466" + ], + "index": "pypi", + "version": "==0.8.1" + } + }, "develop": { "alabaster": { "hashes": [ "sha256:1ee19aca801bbabb5ba3f5f258e4422dfa86f82f3e9cefb0859b283cdd7f62a3", "sha256:a27a4a084d5e690e16e01e03ad2b2e552c61a65469419b907243193de1a84ae2" ], - "markers": "python_full_version >= '3.6.0'", + "markers": "python_version >= '3.6'", "version": "==0.7.13" }, "babel": { "hashes": [ - "sha256:468e6cd1e2b571a1663110fc737e3a7d9069d038e0c9c4a7f158caeeafe4089c", - "sha256:8f8b752c803e9f9e03ff219b644aceb0dbcf081c55a88ea11f86291e60a7bb68" + "sha256:b4246fb7677d3b98f501a39d43396d3cafdc8eadb045f4a31be01863f655c610", + "sha256:cc2d99999cd01d44420ae725a21c9e3711b3aadc7976d6147f622d8581963455" ], "markers": "python_version >= '3.7'", - "version": "==2.12.0" + "version": "==2.12.1" }, "beautifulsoup4": { "hashes": [ - "sha256:0e79446b10b3ecb499c1556f7e228a53e64a2bfcebd455f370d8927cb5b59e39", - "sha256:bc4bdda6717de5a2987436fb8d72f45dc90dd856bdfd512a1314ce90349a0106" + "sha256:2130a5ad7f513200fae61a17abb5e338ca980fa28c439c0571014bc0217e9591", + "sha256:c5fceeaec29d09c84970e47c65f2f0efe57872f7cff494c9691a26ec0ff13234" ], - "markers": "python_full_version >= '3.6.0'", - "version": "==4.11.2" + "markers": "python_version >= '3.6'", + "version": "==4.12.0" }, "certifi": { "hashes": [ "sha256:35824b4c3a97115964b408844d64aa14db1cc518f6562e8d7261699d1350a9e3", "sha256:4ad3232f5e926d6718ec31cfc1fcadfde020920e278684144551c91769c7bc18" ], - "markers": "python_full_version >= '3.6.0'", + "markers": "python_version >= '3.6'", "version": "==2022.12.7" }, "charset-normalizer": { "hashes": [ - "sha256:00d3ffdaafe92a5dc603cb9bd5111aaa36dfa187c8285c543be562e61b755f6b", - "sha256:024e606be3ed92216e2b6952ed859d86b4cfa52cd5bc5f050e7dc28f9b43ec42", - "sha256:0298eafff88c99982a4cf66ba2efa1128e4ddaca0b05eec4c456bbc7db691d8d", - "sha256:02a51034802cbf38db3f89c66fb5d2ec57e6fe7ef2f4a44d070a593c3688667b", - "sha256:083c8d17153ecb403e5e1eb76a7ef4babfc2c48d58899c98fcaa04833e7a2f9a", - "sha256:0a11e971ed097d24c534c037d298ad32c6ce81a45736d31e0ff0ad37ab437d59", - "sha256:0bf2dae5291758b6f84cf923bfaa285632816007db0330002fa1de38bfcb7154", - "sha256:0c0a590235ccd933d9892c627dec5bc7511ce6ad6c1011fdf5b11363022746c1", - "sha256:0f438ae3532723fb6ead77e7c604be7c8374094ef4ee2c5e03a3a17f1fca256c", - "sha256:109487860ef6a328f3eec66f2bf78b0b72400280d8f8ea05f69c51644ba6521a", - "sha256:11b53acf2411c3b09e6af37e4b9005cba376c872503c8f28218c7243582df45d", - "sha256:12db3b2c533c23ab812c2b25934f60383361f8a376ae272665f8e48b88e8e1c6", - "sha256:14e76c0f23218b8f46c4d87018ca2e441535aed3632ca134b10239dfb6dadd6b", - "sha256:16a8663d6e281208d78806dbe14ee9903715361cf81f6d4309944e4d1e59ac5b", - "sha256:292d5e8ba896bbfd6334b096e34bffb56161c81408d6d036a7dfa6929cff8783", - "sha256:2c03cc56021a4bd59be889c2b9257dae13bf55041a3372d3295416f86b295fb5", - "sha256:2e396d70bc4ef5325b72b593a72c8979999aa52fb8bcf03f701c1b03e1166918", - "sha256:2edb64ee7bf1ed524a1da60cdcd2e1f6e2b4f66ef7c077680739f1641f62f555", - "sha256:31a9ddf4718d10ae04d9b18801bd776693487cbb57d74cc3458a7673f6f34639", - "sha256:356541bf4381fa35856dafa6a965916e54bed415ad8a24ee6de6e37deccf2786", - "sha256:358a7c4cb8ba9b46c453b1dd8d9e431452d5249072e4f56cfda3149f6ab1405e", - "sha256:37f8febc8ec50c14f3ec9637505f28e58d4f66752207ea177c1d67df25da5aed", - "sha256:39049da0ffb96c8cbb65cbf5c5f3ca3168990adf3551bd1dee10c48fce8ae820", - "sha256:39cf9ed17fe3b1bc81f33c9ceb6ce67683ee7526e65fde1447c772afc54a1bb8", - "sha256:3ae1de54a77dc0d6d5fcf623290af4266412a7c4be0b1ff7444394f03f5c54e3", - "sha256:3b590df687e3c5ee0deef9fc8c547d81986d9a1b56073d82de008744452d6541", - "sha256:3e45867f1f2ab0711d60c6c71746ac53537f1684baa699f4f668d4c6f6ce8e14", - "sha256:3fc1c4a2ffd64890aebdb3f97e1278b0cc72579a08ca4de8cd2c04799a3a22be", - "sha256:4457ea6774b5611f4bed5eaa5df55f70abde42364d498c5134b7ef4c6958e20e", - "sha256:44ba614de5361b3e5278e1241fda3dc1838deed864b50a10d7ce92983797fa76", - "sha256:4a8fcf28c05c1f6d7e177a9a46a1c52798bfe2ad80681d275b10dcf317deaf0b", - "sha256:4b0d02d7102dd0f997580b51edc4cebcf2ab6397a7edf89f1c73b586c614272c", - "sha256:502218f52498a36d6bf5ea77081844017bf7982cdbe521ad85e64cabee1b608b", - "sha256:503e65837c71b875ecdd733877d852adbc465bd82c768a067badd953bf1bc5a3", - "sha256:5995f0164fa7df59db4746112fec3f49c461dd6b31b841873443bdb077c13cfc", - "sha256:59e5686dd847347e55dffcc191a96622f016bc0ad89105e24c14e0d6305acbc6", - "sha256:601f36512f9e28f029d9481bdaf8e89e5148ac5d89cffd3b05cd533eeb423b59", - "sha256:608862a7bf6957f2333fc54ab4399e405baad0163dc9f8d99cb236816db169d4", - "sha256:62595ab75873d50d57323a91dd03e6966eb79c41fa834b7a1661ed043b2d404d", - "sha256:70990b9c51340e4044cfc394a81f614f3f90d41397104d226f21e66de668730d", - "sha256:71140351489970dfe5e60fc621ada3e0f41104a5eddaca47a7acb3c1b851d6d3", - "sha256:72966d1b297c741541ca8cf1223ff262a6febe52481af742036a0b296e35fa5a", - "sha256:74292fc76c905c0ef095fe11e188a32ebd03bc38f3f3e9bcb85e4e6db177b7ea", - "sha256:761e8904c07ad053d285670f36dd94e1b6ab7f16ce62b9805c475b7aa1cffde6", - "sha256:772b87914ff1152b92a197ef4ea40efe27a378606c39446ded52c8f80f79702e", - "sha256:79909e27e8e4fcc9db4addea88aa63f6423ebb171db091fb4373e3312cb6d603", - "sha256:7e189e2e1d3ed2f4aebabd2d5b0f931e883676e51c7624826e0a4e5fe8a0bf24", - "sha256:7eb33a30d75562222b64f569c642ff3dc6689e09adda43a082208397f016c39a", - "sha256:81d6741ab457d14fdedc215516665050f3822d3e56508921cc7239f8c8e66a58", - "sha256:8499ca8f4502af841f68135133d8258f7b32a53a1d594aa98cc52013fff55678", - "sha256:84c3990934bae40ea69a82034912ffe5a62c60bbf6ec5bc9691419641d7d5c9a", - "sha256:87701167f2a5c930b403e9756fab1d31d4d4da52856143b609e30a1ce7160f3c", - "sha256:88600c72ef7587fe1708fd242b385b6ed4b8904976d5da0893e31df8b3480cb6", - "sha256:8ac7b6a045b814cf0c47f3623d21ebd88b3e8cf216a14790b455ea7ff0135d18", - "sha256:8b8af03d2e37866d023ad0ddea594edefc31e827fee64f8de5611a1dbc373174", - "sha256:8c7fe7afa480e3e82eed58e0ca89f751cd14d767638e2550c77a92a9e749c317", - "sha256:8eade758719add78ec36dc13201483f8e9b5d940329285edcd5f70c0a9edbd7f", - "sha256:911d8a40b2bef5b8bbae2e36a0b103f142ac53557ab421dc16ac4aafee6f53dc", - "sha256:93ad6d87ac18e2a90b0fe89df7c65263b9a99a0eb98f0a3d2e079f12a0735837", - "sha256:95dea361dd73757c6f1c0a1480ac499952c16ac83f7f5f4f84f0658a01b8ef41", - "sha256:9ab77acb98eba3fd2a85cd160851816bfce6871d944d885febf012713f06659c", - "sha256:9cb3032517f1627cc012dbc80a8ec976ae76d93ea2b5feaa9d2a5b8882597579", - "sha256:9cf4e8ad252f7c38dd1f676b46514f92dc0ebeb0db5552f5f403509705e24753", - "sha256:9d9153257a3f70d5f69edf2325357251ed20f772b12e593f3b3377b5f78e7ef8", - "sha256:a152f5f33d64a6be73f1d30c9cc82dfc73cec6477ec268e7c6e4c7d23c2d2291", - "sha256:a16418ecf1329f71df119e8a65f3aa68004a3f9383821edcb20f0702934d8087", - "sha256:a60332922359f920193b1d4826953c507a877b523b2395ad7bc716ddd386d866", - "sha256:a8d0fc946c784ff7f7c3742310cc8a57c5c6dc31631269876a88b809dbeff3d3", - "sha256:ab5de034a886f616a5668aa5d098af2b5385ed70142090e2a31bcbd0af0fdb3d", - "sha256:c22d3fe05ce11d3671297dc8973267daa0f938b93ec716e12e0f6dee81591dc1", - "sha256:c2ac1b08635a8cd4e0cbeaf6f5e922085908d48eb05d44c5ae9eabab148512ca", - "sha256:c512accbd6ff0270939b9ac214b84fb5ada5f0409c44298361b2f5e13f9aed9e", - "sha256:c75ffc45f25324e68ab238cb4b5c0a38cd1c3d7f1fb1f72b5541de469e2247db", - "sha256:c95a03c79bbe30eec3ec2b7f076074f4281526724c8685a42872974ef4d36b72", - "sha256:cadaeaba78750d58d3cc6ac4d1fd867da6fc73c88156b7a3212a3cd4819d679d", - "sha256:cd6056167405314a4dc3c173943f11249fa0f1b204f8b51ed4bde1a9cd1834dc", - "sha256:db72b07027db150f468fbada4d85b3b2729a3db39178abf5c543b784c1254539", - "sha256:df2c707231459e8a4028eabcd3cfc827befd635b3ef72eada84ab13b52e1574d", - "sha256:e62164b50f84e20601c1ff8eb55620d2ad25fb81b59e3cd776a1902527a788af", - "sha256:e696f0dd336161fca9adbb846875d40752e6eba585843c768935ba5c9960722b", - "sha256:eaa379fcd227ca235d04152ca6704c7cb55564116f8bc52545ff357628e10602", - "sha256:ebea339af930f8ca5d7a699b921106c6e29c617fe9606fa7baa043c1cdae326f", - "sha256:f4c39b0e3eac288fedc2b43055cfc2ca7a60362d0e5e87a637beac5d801ef478", - "sha256:f5057856d21e7586765171eac8b9fc3f7d44ef39425f85dbcccb13b3ebea806c", - "sha256:f6f45710b4459401609ebebdbcfb34515da4fc2aa886f95107f556ac69a9147e", - "sha256:f97e83fa6c25693c7a35de154681fcc257c1c41b38beb0304b9c4d2d9e164479", - "sha256:f9d0c5c045a3ca9bedfc35dca8526798eb91a07aa7a2c0fee134c6c6f321cbd7", - "sha256:ff6f3db31555657f3163b15a6b7c6938d08df7adbfc9dd13d9d19edad678f1e8" - ], - "version": "==3.0.1" + "sha256:04afa6387e2b282cf78ff3dbce20f0cc071c12dc8f685bd40960cc68644cfea6", + "sha256:04eefcee095f58eaabe6dc3cc2262f3bcd776d2c67005880894f447b3f2cb9c1", + "sha256:0be65ccf618c1e7ac9b849c315cc2e8a8751d9cfdaa43027d4f6624bd587ab7e", + "sha256:0c95f12b74681e9ae127728f7e5409cbbef9cd914d5896ef238cc779b8152373", + "sha256:0ca564606d2caafb0abe6d1b5311c2649e8071eb241b2d64e75a0d0065107e62", + "sha256:10c93628d7497c81686e8e5e557aafa78f230cd9e77dd0c40032ef90c18f2230", + "sha256:11d117e6c63e8f495412d37e7dc2e2fff09c34b2d09dbe2bee3c6229577818be", + "sha256:11d3bcb7be35e7b1bba2c23beedac81ee893ac9871d0ba79effc7fc01167db6c", + "sha256:12a2b561af122e3d94cdb97fe6fb2bb2b82cef0cdca131646fdb940a1eda04f0", + "sha256:12d1a39aa6b8c6f6248bb54550efcc1c38ce0d8096a146638fd4738e42284448", + "sha256:1435ae15108b1cb6fffbcea2af3d468683b7afed0169ad718451f8db5d1aff6f", + "sha256:1c60b9c202d00052183c9be85e5eaf18a4ada0a47d188a83c8f5c5b23252f649", + "sha256:1e8fcdd8f672a1c4fc8d0bd3a2b576b152d2a349782d1eb0f6b8e52e9954731d", + "sha256:20064ead0717cf9a73a6d1e779b23d149b53daf971169289ed2ed43a71e8d3b0", + "sha256:21fa558996782fc226b529fdd2ed7866c2c6ec91cee82735c98a197fae39f706", + "sha256:22908891a380d50738e1f978667536f6c6b526a2064156203d418f4856d6e86a", + "sha256:3160a0fd9754aab7d47f95a6b63ab355388d890163eb03b2d2b87ab0a30cfa59", + "sha256:322102cdf1ab682ecc7d9b1c5eed4ec59657a65e1c146a0da342b78f4112db23", + "sha256:34e0a2f9c370eb95597aae63bf85eb5e96826d81e3dcf88b8886012906f509b5", + "sha256:3573d376454d956553c356df45bb824262c397c6e26ce43e8203c4c540ee0acb", + "sha256:3747443b6a904001473370d7810aa19c3a180ccd52a7157aacc264a5ac79265e", + "sha256:38e812a197bf8e71a59fe55b757a84c1f946d0ac114acafaafaf21667a7e169e", + "sha256:3a06f32c9634a8705f4ca9946d667609f52cf130d5548881401f1eb2c39b1e2c", + "sha256:3a5fc78f9e3f501a1614a98f7c54d3969f3ad9bba8ba3d9b438c3bc5d047dd28", + "sha256:3d9098b479e78c85080c98e1e35ff40b4a31d8953102bb0fd7d1b6f8a2111a3d", + "sha256:3dc5b6a8ecfdc5748a7e429782598e4f17ef378e3e272eeb1340ea57c9109f41", + "sha256:4155b51ae05ed47199dc5b2a4e62abccb274cee6b01da5b895099b61b1982974", + "sha256:49919f8400b5e49e961f320c735388ee686a62327e773fa5b3ce6721f7e785ce", + "sha256:53d0a3fa5f8af98a1e261de6a3943ca631c526635eb5817a87a59d9a57ebf48f", + "sha256:5f008525e02908b20e04707a4f704cd286d94718f48bb33edddc7d7b584dddc1", + "sha256:628c985afb2c7d27a4800bfb609e03985aaecb42f955049957814e0491d4006d", + "sha256:65ed923f84a6844de5fd29726b888e58c62820e0769b76565480e1fdc3d062f8", + "sha256:6734e606355834f13445b6adc38b53c0fd45f1a56a9ba06c2058f86893ae8017", + "sha256:6baf0baf0d5d265fa7944feb9f7451cc316bfe30e8df1a61b1bb08577c554f31", + "sha256:6f4f4668e1831850ebcc2fd0b1cd11721947b6dc7c00bf1c6bd3c929ae14f2c7", + "sha256:6f5c2e7bc8a4bf7c426599765b1bd33217ec84023033672c1e9a8b35eaeaaaf8", + "sha256:6f6c7a8a57e9405cad7485f4c9d3172ae486cfef1344b5ddd8e5239582d7355e", + "sha256:7381c66e0561c5757ffe616af869b916c8b4e42b367ab29fedc98481d1e74e14", + "sha256:73dc03a6a7e30b7edc5b01b601e53e7fc924b04e1835e8e407c12c037e81adbd", + "sha256:74db0052d985cf37fa111828d0dd230776ac99c740e1a758ad99094be4f1803d", + "sha256:75f2568b4189dda1c567339b48cba4ac7384accb9c2a7ed655cd86b04055c795", + "sha256:78cacd03e79d009d95635e7d6ff12c21eb89b894c354bd2b2ed0b4763373693b", + "sha256:80d1543d58bd3d6c271b66abf454d437a438dff01c3e62fdbcd68f2a11310d4b", + "sha256:830d2948a5ec37c386d3170c483063798d7879037492540f10a475e3fd6f244b", + "sha256:891cf9b48776b5c61c700b55a598621fdb7b1e301a550365571e9624f270c203", + "sha256:8f25e17ab3039b05f762b0a55ae0b3632b2e073d9c8fc88e89aca31a6198e88f", + "sha256:9a3267620866c9d17b959a84dd0bd2d45719b817245e49371ead79ed4f710d19", + "sha256:a04f86f41a8916fe45ac5024ec477f41f886b3c435da2d4e3d2709b22ab02af1", + "sha256:aaf53a6cebad0eae578f062c7d462155eada9c172bd8c4d250b8c1d8eb7f916a", + "sha256:abc1185d79f47c0a7aaf7e2412a0eb2c03b724581139193d2d82b3ad8cbb00ac", + "sha256:ac0aa6cd53ab9a31d397f8303f92c42f534693528fafbdb997c82bae6e477ad9", + "sha256:ac3775e3311661d4adace3697a52ac0bab17edd166087d493b52d4f4f553f9f0", + "sha256:b06f0d3bf045158d2fb8837c5785fe9ff9b8c93358be64461a1089f5da983137", + "sha256:b116502087ce8a6b7a5f1814568ccbd0e9f6cfd99948aa59b0e241dc57cf739f", + "sha256:b82fab78e0b1329e183a65260581de4375f619167478dddab510c6c6fb04d9b6", + "sha256:bd7163182133c0c7701b25e604cf1611c0d87712e56e88e7ee5d72deab3e76b5", + "sha256:c36bcbc0d5174a80d6cccf43a0ecaca44e81d25be4b7f90f0ed7bcfbb5a00909", + "sha256:c3af8e0f07399d3176b179f2e2634c3ce9c1301379a6b8c9c9aeecd481da494f", + "sha256:c84132a54c750fda57729d1e2599bb598f5fa0344085dbde5003ba429a4798c0", + "sha256:cb7b2ab0188829593b9de646545175547a70d9a6e2b63bf2cd87a0a391599324", + "sha256:cca4def576f47a09a943666b8f829606bcb17e2bc2d5911a46c8f8da45f56755", + "sha256:cf6511efa4801b9b38dc5546d7547d5b5c6ef4b081c60b23e4d941d0eba9cbeb", + "sha256:d16fd5252f883eb074ca55cb622bc0bee49b979ae4e8639fff6ca3ff44f9f854", + "sha256:d2686f91611f9e17f4548dbf050e75b079bbc2a82be565832bc8ea9047b61c8c", + "sha256:d7fc3fca01da18fbabe4625d64bb612b533533ed10045a2ac3dd194bfa656b60", + "sha256:dd5653e67b149503c68c4018bf07e42eeed6b4e956b24c00ccdf93ac79cdff84", + "sha256:de5695a6f1d8340b12a5d6d4484290ee74d61e467c39ff03b39e30df62cf83a0", + "sha256:e0ac8959c929593fee38da1c2b64ee9778733cdf03c482c9ff1d508b6b593b2b", + "sha256:e1b25e3ad6c909f398df8921780d6a3d120d8c09466720226fc621605b6f92b1", + "sha256:e633940f28c1e913615fd624fcdd72fdba807bf53ea6925d6a588e84e1151531", + "sha256:e89df2958e5159b811af9ff0f92614dabf4ff617c03a4c1c6ff53bf1c399e0e1", + "sha256:ea9f9c6034ea2d93d9147818f17c2a0860d41b71c38b9ce4d55f21b6f9165a11", + "sha256:f645caaf0008bacf349875a974220f1f1da349c5dbe7c4ec93048cdc785a3326", + "sha256:f8303414c7b03f794347ad062c0516cee0e15f7a612abd0ce1e25caf6ceb47df", + "sha256:fca62a8301b605b954ad2e9c3666f9d97f63872aa4efcae5492baca2056b74ab" + ], + "markers": "python_version >= '3.7'", + "version": "==3.1.0" }, "colorama": { "hashes": [ @@ -160,11 +157,11 @@ }, "furo": { "hashes": [ - "sha256:7cb76c12a25ef65db85ab0743df907573d03027a33631f17d267e598ebb191f7", - "sha256:d8008f8efbe7587a97ba533c8b2df1f9c21ee9b3e5cad0d27f61193d38b1a986" + "sha256:1cdf0730496f6ac0ecf394845fe55010539d987a3085f29d819e49a8e87da60a", + "sha256:6cf9a59fe2919693ecff6509a08229afa081583cbb5b81f59c3e755f3bd81d26" ], "index": "pypi", - "version": "==2022.12.7" + "version": "==2023.3.23" }, "idna": { "hashes": [ @@ -202,7 +199,7 @@ "sha256:5a35f8d1870171d9acc47b99612dc146129b631baf04970128b568f190d0cc30", "sha256:7c9a5e412688bc771c67432cbfebcdd686c93ce6484913dccf06cb5a0bea35a1" ], - "index": "pypi", + "markers": "python_version >= '3.7'", "version": "==2.2.0" }, "markupsafe": { @@ -263,11 +260,11 @@ }, "mdit-py-plugins": { "hashes": [ - "sha256:3278aab2e2b692539082f05e1243f24742194ffd92481f48844f057b51971283", - "sha256:4f1441264ac5cb39fa40a5901921c2acf314ea098d75629750c138f80d552cdf" + "sha256:ca9a0714ea59a24b2b044a1831f48d817dd0c817e84339f20e7889f392d77c4e", + "sha256:eee0adc7195e5827e17e02d2a258a2ba159944a0748f59c5099a4a27f78fcf6a" ], "markers": "python_version >= '3.7'", - "version": "==0.3.4" + "version": "==0.3.5" }, "mdurl": { "hashes": [ @@ -279,11 +276,11 @@ }, "myst-parser": { "hashes": [ - "sha256:61b275b85d9f58aa327f370913ae1bec26ebad372cc99f3ab85c8ec3ee8d9fb8", - "sha256:79317f4bb2c13053dd6e64f9da1ba1da6cd9c40c8a430c447a7b146a594c246d" + "sha256:502845659313099542bd38a2ae62f01360e7dd4b1310f025dd014dfc0439cdae", + "sha256:69fb40a586c6fa68995e6521ac0a525793935db7e724ca9bac1d33be51be9a4c" ], "index": "pypi", - "version": "==0.18.1" + "version": "==1.0.0" }, "packaging": { "hashes": [ @@ -298,7 +295,7 @@ "sha256:b3ed06a9e8ac9a9aae5a6f5dbe78a8a58655d17b43b93c078f094ddc476ae297", "sha256:fa7bd7bd2771287c0de303af8bfdfc731f51bd2c6a47ab69d117138893b82717" ], - "markers": "python_full_version >= '3.6.0'", + "markers": "python_version >= '3.6'", "version": "==2.14.0" }, "pyyaml": { @@ -344,7 +341,7 @@ "sha256:e61ceaab6f49fb8bdfaa0f92c4b57bcfbea54c09277b1b4f7ac376bfb7a7c174", "sha256:f84fbc98b019fef2ee9a1cb3ce93e3187a6df0b2538a651bfb890254ba9f90b5" ], - "markers": "python_full_version >= '3.6.0'", + "markers": "python_version >= '3.6'", "version": "==6.0" }, "requests": { @@ -380,11 +377,11 @@ }, "sphinx": { "hashes": [ - "sha256:060ca5c9f7ba57a08a1219e547b269fadf125ae25b06b9fa7f66768efb652d6d", - "sha256:51026de0a9ff9fc13c05d74913ad66047e104f56a129ff73e174eb5c3ee794b5" + "sha256:0dac3b698538ffef41716cf97ba26c1c7788dba73ce6f150c1ff5b4720786dd2", + "sha256:807d1cb3d6be87eb78a381c3e70ebd8d346b9a25f3753e9947e866b2786865fc" ], "index": "pypi", - "version": "==5.3.0" + "version": "==6.1.3" }, "sphinx-autobuild": { "hashes": [ @@ -434,6 +431,14 @@ "markers": "python_version >= '3.5'", "version": "==1.0.1" }, + "sphinxcontrib-mermaid": { + "hashes": [ + "sha256:15491c24ec78cf1626b1e79e797a9ce87cb7959cf38f955eb72dd5512aeb6ce9", + "sha256:fa3e5325d4ba395336e6137d113f55026b1a03ccd115dc54113d1d871a580466" + ], + "index": "pypi", + "version": "==0.8.1" + }, "sphinxcontrib-qthelp": { "hashes": [ "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72", @@ -467,21 +472,13 @@ "markers": "python_version > '2.7'", "version": "==6.2" }, - "typing-extensions": { - "hashes": [ - "sha256:5cb5f4a79139d699607b3ef622a1dedafa84e115ab0024e0d9c044a9479ca7cb", - "sha256:fb33085c39dd998ac16d1431ebc293a8b3eedd00fd4a32de0ff79002c19511b4" - ], - "markers": "python_version >= '3.7'", - "version": "==4.5.0" - }, "urllib3": { "hashes": [ - "sha256:076907bf8fd355cde77728471316625a4d2f7e713c125f51953bb5b3eecf4f72", - "sha256:75edcdc2f7d85b137124a6c3c9fc3933cdeaa12ecb9a6a959f22797a0feca7e1" + "sha256:8a388717b9476f934a21484e8c8e61875ab60644d29b9b39e11e4b9dc1c6b305", + "sha256:aa751d169e23c7479ce47a0cb0da579e3ede798f994f5816a74e4f4500dcea42" ], "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5'", - "version": "==1.26.14" + "version": "==1.26.15" } } } diff --git a/documentation/conf.py b/documentation/conf.py index 6dfa216b051..4c34a732e59 100644 --- a/documentation/conf.py +++ b/documentation/conf.py @@ -27,7 +27,7 @@ def add_ext_to_path(): # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ["myst_parser", "link_issues"] +extensions = ["myst_parser", "sphinxcontrib.mermaid", "link_issues"] myst_heading_anchors = 6 # Add anchors to all headers, this is disabled by default. source_suffix = {".rst": "restructuredtext", ".md": "markdown"} diff --git a/documentation/reference/consent_decision_making.md b/documentation/reference/consent_decision_making.md index 8985f1d7ce7..6f9405ebfd4 100644 --- a/documentation/reference/consent_decision_making.md +++ b/documentation/reference/consent_decision_making.md @@ -29,19 +29,19 @@ process. The differences come from two directions: - Internal feedback and iteration on the initial process, even after modification for asynchrony -> ## When to follow this process -> -> Whether this process is followed for any given proposal or discussion is left -> entirely to the discretion of the people relevant to the discussion. We -> believe that this process helps the project's contributors make expedient and -> clear decisions. However, it should not become an obstacle that is followed -> for every tiny decision. If a decision can efficiently be made without this -> process, contributors are invited to do so. -> -> For the purposes of project planning, however, this process should be the -> default and should be the strong preference, keeping in mind that it can be -> made faster via [round shortcutting](#shortcutting-a-round) and the -> [synchronous lightening process](#optional-synchronous-lightening-process). +## When to follow this process + +Whether this process is followed for any given proposal or discussion is left +entirely to the discretion of the people relevant to the discussion. We believe +that this process helps the project's contributors make expedient and clear +decisions. However, it should not become an obstacle that is followed for every +tiny decision. If a decision can efficiently be made without this process, +contributors are invited to do so. + +For the purposes of project planning, however, this process should be the +default and should be the strong preference, keeping in mind that it can be made +faster via [round shortcutting](#shortcutting-a-round) and the +[synchronous lightening process](#optional-synchronous-lightening-process). ## Continuous improvement and exceptions to every rule @@ -100,15 +100,29 @@ process. > encapsulate the full scope of the round. Please refer to the > [round descriptions below](#round-descriptions) for more details and examples. -| round | Suggested span | Goal | +| Round | Suggested span | Goal | | ----------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------- | -| [Question round](#question-round) | 3 days | Clarify the proposal; share initial reactions | +| [Clarification round](#clarification-round) | 3 days | Clarify the proposal; share initial reactions | | [Revision round](#revision-round) | Author's discretion | Update the text of the proposal to reflect the outcome of the previous round | -| [Objection round](#objection-round) | 2 days | Identify paramount and non-paramount objections | +| [Decision round](#decision-round) | 2 days | Decide whether the proposal can be implemented as is | | [Objection revision round](#objection-revision-round) | Author's discretion | Work with participants to revise the text of the proposal to address paramount objections | | [Approval](#approval) | N/A | Mark as approved and create issues to implement the proposal | | [Tabling](#tabling) | N/A | Indicate that a proposal will not be implemented | +```{mermaid} +flowchart TD + A[Proposal] --> B(Clarification Round) + B -->|Time: 3 days| C(Revision Round (if needed)) + C -->|Time: As needed/estimated by author| D(Decision round) + D -->|Time: 2 days| E(Objection revision (if needed)) + E -->|Time: As needed/estimated by author| F{Decision} + F -->|Insurmountable objections| G[Proposal tabled] + F -->|No objections| H[Proposal accepted] + G -->|New proposal needed| A + H --> I((End)) + G --> I +``` + ## Proposal requirements Project proposals and technical implementation plans should follow the formats @@ -123,33 +137,36 @@ or at the top of the GitHub Discussion: ## Decision-making process For the purposes of this discussion, we will follow -[Openverse's decision-making model](https://wordpress.github.io/openverse/reference/consent_decision_making.html). +[Openverse's decision-making model](https://docs.openverse.org/reference/consent_decision_making.html). This process follows formalised steps with specific expectations of participants. Before contributing, please read -[this document](https://wordpress.github.io/openverse/reference/consent_decision_making.html) +[this document](https://docs.openverse.org/reference/consent_decision_making.html) as well as [Openverse's Code of Conduct](https://github.com/WordPress/openverse/blob/main/CODE_OF_CONDUCT.md). The consent decision-making document linked above also includes instructions for opting out of a decision discussion you do not wish to or cannot participate in. +If you've been asked to give input on this discussion but do not need to +participate in the full decision-making process, please provide your +feedback/input however best fits the needs of the discussion. + ## Current round -The discussion is currently in the **{Question, Revision, Objection, Objection revision}** round. +The discussion is currently in the **{Clarification, Revision, Decision, +Objection revision}** round. ``` ## Round descriptions The following general guidelines apply to all rounds: -- Reactions may be shared at any of the "feedback" rounds (Question and - Objection). -- Proposal authors are not obligated to respond to every question, reaction, or - objection that is raised, except for paramount objections. While there is an - expectation that the author will address outstanding questions, it isn't - necessary to respond to every non-paramount objection before moving on to - subsequent rounds or ratifying the proposal. It is, of course, in the best - interest of the project and the proposal that as much clarity as possible is - achieved. +- Reactions may be shared at any time +- Proposal authors are not obligated to respond to every piece of feedback, + except for paramount objections. While there is an expectation that the author + will address outstanding questions, it isn't necessary to respond to every + non-paramount objection before moving on to subsequent rounds or marking the + proposal as approved. It is, of course, in the best interest of the project + and the proposal that as much clarity as possible is achieved. - Authors may table a proposal at any time at their discretion. If the proposal is tabled, discussion should not be expected to continue, but may, if there is something important being discussed. @@ -157,16 +174,14 @@ The following general guidelines apply to all rounds: [shortcutting as described below](#shortcutting-a-round) or to extension at the discretion of the participants. -### Question round +### Clarification round -The goal of the question round is for everyone participating to fully understand -the proposal. +The suggested length of this round is 3 business days. The goal of the +clarification round is to ensure everyone participating fully understands the +proposal. The focus of the round should be on asking clarifying questions and +uncovering hidden assumptions or gaps in the proposal. -The round lasts for 3 business days but can be extended if important gaps in the -proposal are found that would delay revision. Questions are different from -objections in that they're not in the form of "we cannot do this because x part -of the proposal will not work". Rather, they are clarifying questions in the -form of: +Some examples of helpful clarifying questions are: - "I don't understand y in the proposal, can you clarify what is meant by this?" - "I think a gap exists in the proposed solution here [clarify where]. Can you @@ -183,20 +198,6 @@ Note that the author does not have to respond to _every_ question. However, they should keep them in mind during the revision round with the understanding that the questions are shared in order to clarify the proposal. -#### Reactions - -This round also invites participants to share reactions, positive or negative, -separate from potential paramount objections. This is an excellent round to -highlight positive aspects of the proposal, regardless of any paramount -objections. You may also share non-paramount objections at this round. For -example, "I find JavaScript harder to work with than Python" is an objection but -not a paramount objection. What makes an objection "paramount" is clarified -further in the [Objection round](#objection-round) below. - -Reactions are expected during this round because, similar to questions, they can -help prompt further clarification from the author to be address in the revision -round. - #### Purpose Proposals must all include an explicit "purpose". Often these are informed by @@ -210,30 +211,36 @@ is taken to be accepted and should not be the focus of the discussion. ### Revision round -At this round, the author has the opportunity to revise the proposal in response -to the questions and reactions raised. This round has no set time period. The -author should use their discretion and give an expected time when the revised -version will be ready. The expected date of completion for the revision is both -for accountability (to prevent projects from being stalled indefinitely) and for -clarity of expectations for the other participants in the process. If the author -requires additional time beyond their initial estimation, they should let the -other participants know as soon as possible, keeping in mind that other -discussions may be stalled in the meantime. +The goal of this round is to revise the proposal to include the clarifications +from the discussion in the previous round. What feedback is incorporated into +the document is at the discretion of the author. + +This round has no set time period. The author should use their discretion and +give an expected time when the revised version will be ready. The expected date +of completion for the revision is both for accountability (to prevent projects +from being stalled indefinitely) and for clarity of expectations for the other +participants in the process. If the author requires additional time beyond their +initial estimation, they should let the other participants know as soon as +possible, keeping in mind that other discussions may be stalled in the meantime. **No revisions should be made to the proposal before this point other than grammatical or spelling corrections**. The reason for this is to allow the -question round to fully complete without the proposal changing during the +clarification round to fully complete without the proposal changing during the discussion. This allows clarification to happen fully without having to track ongoing changes to the proposal. It also sets the expectation that revisions to the proposal address the questions and reactions in full. This helps to minimise the potentially "frantic" nature of a discussion that is happening about a proposal document that is changing simultaneously with the discussion. -### Objection round +### Decision round + +This round lasts for 2 business days. The goal of this round is to decide +whether the proposal can be implemented. Participants are asked to share +objections to the proposal if they do not think it can be implemented. -This round lasts for 2 business days. Participants are now invited to share -"paramount objections" to the proposal, if any exist. Objections are considered -"paramount" only if: +There are two types of objections, paramount and non-paramount. Participants +must explicitly say which type of objection each of their objections falls +under. Objections are considered "paramount" only if: - They point to an issue that prevents the team from achieving its goals (whether these are technical, community, or interpersonal). These issues can @@ -246,14 +253,14 @@ This round lasts for 2 business days. Participants are now invited to share that it is the best decision, then any objection to making the switch would be paramount. -During this round, as in the question round, the author should not modify the -text of the proposal. The focus of the author in this round should be to clarify -objections (especially paramount objections) and decide whether the proposal can -address them. This allows time for participants to fully digest the proposal and -raise all objections without further revision happening. Participants are -expected to help each other decide whether an objection is paramount. Whether an -objection is paramount can be questioned by the author, but they should prefer -to defer to the participants and trust their judgement. +During this round, as in the clarification round, the author should not modify +the text of the proposal. The focus of the author in this round should be to +clarify objections (especially paramount objections) and decide whether the +proposal can address them. This allows time for participants to fully digest the +proposal and raise all objections without further revision happening. +Participants are expected to help each other decide whether an objection is +paramount. Whether an objection is paramount can be questioned by the author, +but they should prefer to defer to the participants and trust their judgement. If there are no paramount objections then the process has finished and the proposal is [approved](#approval). @@ -320,7 +327,7 @@ Tabling can occur in the following cases: - Before a proposal is written, if the team reneges on a requested discussion - After a proposal is written, but before the discussion happens, if it is clear the proposal will not fit the needs of the project -- During the objection round when insurmountable paramount objections are raised +- During the decision round when insurmountable paramount objections are raised In the final case, the participants of the discussion are responsible for deciding whether a new proposal should be requested. @@ -470,17 +477,15 @@ the lightening process. Differences in structure for the "lightening process" from the asynchronous process are as follows: -- Rather than tying the question and reaction rounds together, they are separate - rounds. Therefore, the rounds are as follows: - 1. Question +- We have a separate round for reactions. Therefore, the rounds are as follows: + 1. Clarification 1. Reaction 1. Revision - 1. Objection + 1. Decision 1. Objection revision -- Each round should have notes taken clearly documenting the questions, - reactions, objections, and discussions for each (as appropriate). Priority - should be given to questions and objections that require revising the - proposal. +- Each round should have notes taken clearly documenting the feedback and + discussions for each (as appropriate). Priority should be given to questions + and objections that require revising the proposal. ## How to follow the process in different settings @@ -507,32 +512,31 @@ GitHub PRs have the following ways of interacting with comments: Each of these can serve their own purposes: - Inline comments - - These are perfect to supplement the question and objection rounds. If a - question is about a specific part of the proposal (rather than a more - general clarification), participants can leave the question directly on the - part in question. Similarly, paramount objections specific to one part of - the proposal can be left as inline comments attached to a review requesting - changes. + - These are perfect to supplement the clarification and decision rounds. If a + request for clarification is about a specific part of the proposal (rather + than a more general clarification), participants can leave the question + directly on the relevant part of the proposal. Similarly, paramount + objections specific to one part of the proposal can be left as inline + comments attached to a review requesting changes. - General PR comments - For questions or non-paramount objections raised regarding the proposal in general or for the reaction round. - In addition to the PR description, the author of the PR will also create a new top-level PR comment when a new round starts. - Review comments - - These should be used in the objection raising round. Leave an approving - review if you have no paramount objections or "request changes" if you have - a paramount objection. Attach inline comments as needed in either case. + - These should be used in the decision round. Leave an approving review if you + have no paramount objections or "request changes" if you have a paramount + objection. Attach inline comments as needed in either case. ### GitHub Discussions Because the format is slightly more limited than PRs, we will have a top-level comment per round created by the author. Responses from participants should be contained within the thread for each round. However, paramount objections during -the Objection round, should be raised as individual threads. Still, the author +the decision round, should be raised as individual threads. Still, the author should still create a top-level comment closing the previous round and opening -the objection round. If the proposal goes into objection revision, the -discussion for addressing a given objection can happen in the accompanying -thread. +the decision round. If the proposal goes into objection revision, the discussion +for addressing a given objection can happen in the accompanying thread. ## Major differences from the original process diff --git a/documentation/reference/index.md b/documentation/reference/index.md index d480d87144c..0b00a4cbb9e 100644 --- a/documentation/reference/index.md +++ b/documentation/reference/index.md @@ -4,6 +4,7 @@ :maxdepth: 1 github_contribution_practices +consent_decision_making dev_flow api/index frontend/index From 1a1da7b747a00d37bb071447032374fed2a28b87 Mon Sep 17 00:00:00 2001 From: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> Date: Mon, 27 Mar 2023 15:22:07 +1100 Subject: [PATCH 11/14] Simplify wording; add cross-ref links; fix diagram syntax --- .../reference/consent_decision_making.md | 31 ++++++++++--------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/documentation/reference/consent_decision_making.md b/documentation/reference/consent_decision_making.md index 6f9405ebfd4..e5fe911932b 100644 --- a/documentation/reference/consent_decision_making.md +++ b/documentation/reference/consent_decision_making.md @@ -9,25 +9,24 @@ We hope this will accomplish the following: - Clarify the types of feedback expected during the decision-making process, including which types of feedback must be addressed and which are marginal before a proposal can be approved for implementation -- Give specificity in feedback expectations, both for who will participate in a - decision-making process and what responsibilities and tools they have for - participating +- Make participant expectations specific, including making explicit who will + participate in a given decision-making process and what responsibilities and + tools they have for participating - Reaffirm trust between contributors when evaluating proposals Historically, each of these have presented problems for the Openverse project as it has grown. Decision-making can drag on for months, proposal reviews get stuck in feedback cycles over issues that could be addressed later on, and there were -few, if any, expectations around who would participate in a discussion or what -the expectations of that participation was. Adopting the process described -below, we hope, will address some of the underlying causes of these problems, in +few, if any, expectations for who would participate in a discussion or what the +expectations were of that participation. Adopting the process described below, +we hope, will address some of the underlying causes of these problems, in addition to the benefits described above. The process described below is heavily modified from the regular Sociocratic process. The differences come from two directions: - The needs of an asynchronously coordinated base of contributors -- Internal feedback and iteration on the initial process, even after - modification for asynchrony +- Internal feedback and iteration on the process ## When to follow this process @@ -109,12 +108,14 @@ process. | [Approval](#approval) | N/A | Mark as approved and create issues to implement the proposal | | [Tabling](#tabling) | N/A | Indicate that a proposal will not be implemented | +## Process diagram + ```{mermaid} flowchart TD A[Proposal] --> B(Clarification Round) - B -->|Time: 3 days| C(Revision Round (if needed)) + B -->|Time: 3 days| C("Revision Round (if needed)") C -->|Time: As needed/estimated by author| D(Decision round) - D -->|Time: 2 days| E(Objection revision (if needed)) + D -->|Time: 2 days| E("Objection revision (if needed)") E -->|Time: As needed/estimated by author| F{Decision} F -->|Insurmountable objections| G[Proposal tabled] F -->|No objections| H[Proposal accepted] @@ -127,8 +128,8 @@ flowchart TD Project proposals and technical implementation plans should follow the formats outlined in [the documentation for those processes](./docs/projects/README.md). -All proposals should include a summary of the purpose of the proposal and the -problem(s) it attempts to address. +All proposals should include a summary of the +[purpose of the proposal](#purpose) and the problem(s) it attempts to address. Every proposal must include the following boilerplate text in the PR description or at the top of the GitHub Discussion: @@ -146,8 +147,8 @@ as well as The consent decision-making document linked above also includes instructions for opting out of a decision discussion you do not wish to or cannot participate in. -If you've been asked to give input on this discussion but do not need to -participate in the full decision-making process, please provide your +**If you've been asked to give input on this discussion but do not need to +participate in the full decision-making process**, please provide your feedback/input however best fits the needs of the discussion. ## Current round @@ -160,7 +161,7 @@ Objection revision}** round. The following general guidelines apply to all rounds: -- Reactions may be shared at any time +- [Reactions](#reactions) may be shared at any time - Proposal authors are not obligated to respond to every piece of feedback, except for paramount objections. While there is an expectation that the author will address outstanding questions, it isn't necessary to respond to every From a9c787496e9149e6246219eb99d79b4559e60007 Mon Sep 17 00:00:00 2001 From: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> Date: Fri, 31 Mar 2023 11:57:30 +1100 Subject: [PATCH 12/14] Rewrite decision making document to significantly simplify --- documentation/index.md | 2 +- .../reference/consent_decision_making.md | 579 ------------------ .../decision_making/additional_practices.md | 149 +++++ .../reference/decision_making/index.md | 15 + .../decision_making/process_description.md | 187 ++++++ documentation/reference/index.md | 4 +- 6 files changed, 354 insertions(+), 582 deletions(-) delete mode 100644 documentation/reference/consent_decision_making.md create mode 100644 documentation/reference/decision_making/additional_practices.md create mode 100644 documentation/reference/decision_making/index.md create mode 100644 documentation/reference/decision_making/process_description.md diff --git a/documentation/index.md b/documentation/index.md index 5fc56893b22..4dde54ef98d 100644 --- a/documentation/index.md +++ b/documentation/index.md @@ -25,7 +25,7 @@ use the Openverse API, you should instead refer to the ## Table of contents ```{toctree} -:maxdepth: 2 +:maxdepth: 3 guides/index reference/index diff --git a/documentation/reference/consent_decision_making.md b/documentation/reference/consent_decision_making.md deleted file mode 100644 index e5fe911932b..00000000000 --- a/documentation/reference/consent_decision_making.md +++ /dev/null @@ -1,579 +0,0 @@ -# Consent decision-making - -The Openverse project uses a decision-making model based on the -[Sociocracy practice of "consent decision-making"](https://patterns.sociocracy30.org/consent-decision-making.html). -We hope this will accomplish the following: - -- Bring expediency to decision-making by giving guidelines for how and what - types of feedback to give -- Clarify the types of feedback expected during the decision-making process, - including which types of feedback must be addressed and which are marginal - before a proposal can be approved for implementation -- Make participant expectations specific, including making explicit who will - participate in a given decision-making process and what responsibilities and - tools they have for participating -- Reaffirm trust between contributors when evaluating proposals - -Historically, each of these have presented problems for the Openverse project as -it has grown. Decision-making can drag on for months, proposal reviews get stuck -in feedback cycles over issues that could be addressed later on, and there were -few, if any, expectations for who would participate in a discussion or what the -expectations were of that participation. Adopting the process described below, -we hope, will address some of the underlying causes of these problems, in -addition to the benefits described above. - -The process described below is heavily modified from the regular Sociocratic -process. The differences come from two directions: - -- The needs of an asynchronously coordinated base of contributors -- Internal feedback and iteration on the process - -## When to follow this process - -Whether this process is followed for any given proposal or discussion is left -entirely to the discretion of the people relevant to the discussion. We believe -that this process helps the project's contributors make expedient and clear -decisions. However, it should not become an obstacle that is followed for every -tiny decision. If a decision can efficiently be made without this process, -contributors are invited to do so. - -For the purposes of project planning, however, this process should be the -default and should be the strong preference, keeping in mind that it can be made -faster via [round shortcutting](#shortcutting-a-round) and the -[synchronous lightening process](#optional-synchronous-lightening-process). - -## Continuous improvement and exceptions to every rule - -**This process is not set in stone.** Nor is it a set of laws that must be -followed at all times. This document uses prescriptive language. However, keep -in mind that broad qualifications exist and are described in this section. The -document avoids qualifying every imperative in order to prevent the text from -ballooning in size and complexity. - -As with every other aspect of our ever evolving processes, this process is -merely a guideline that we expect contributors to adhere to. It cannot cover -every situation and undoubtedly there are exceptional situations where following -the process to the letter would be antithetical to the goals of the project and -even of the process itself. - -If you have ideas for improving the Openverse decision-making process, please -share them. Any contributor may provide feedback on this process. - -## Terms - -- "Author": The person making the proposal. -- "Participants": All participants of the decision-making process, including the - author, the requested participants, and ad-hoc participants. -- "Reactions": A broad class of feedback that can include personal preferences - as well as general doubts about the validity or safety of the solutions - described in the proposal. -- "Question": A request for clarification, explanation, or additional - information about an aspect of the proposal. -- "Objection": An explained uncertainty about the appropriateness, efficacy, or - safety of a solution -- "Paramount objection": An objection outlining an issue that would cause harm - to the project or its contributors; especially issues that could cause harm - and are difficult to reverse and not strictly necessary to accomplish the - goals of the project -- "Approved proposal": A proposal that has undergone the formal decision-making - process and has been accepted as a valid solution by the participants of the - discussion. -- "Process proposal": A proposal to change processes followed by the - contributors in the course of stewarding the project towards success. -- "Purpose": The motivation for the proposal. This is typically a statement - describing the problem the proposal aims to solve. In the original Sociocratic - model this is called the "driver". - -## Process summary - -The process breaks proposal evaluation and decision-making into a series of -rounds. Each round has expectations about what kinds of feedback are -appropriate. These steps are ordered and must be followed in the order they are -presented here. - -Full descriptions for each of these rounds are below. This section is a summary -meant to give an overview for people new to or refreshing themselves on the -process. - -> **Note** The "goal" column is a very brief summary and is not intended to -> encapsulate the full scope of the round. Please refer to the -> [round descriptions below](#round-descriptions) for more details and examples. - -| Round | Suggested span | Goal | -| ----------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------- | -| [Clarification round](#clarification-round) | 3 days | Clarify the proposal; share initial reactions | -| [Revision round](#revision-round) | Author's discretion | Update the text of the proposal to reflect the outcome of the previous round | -| [Decision round](#decision-round) | 2 days | Decide whether the proposal can be implemented as is | -| [Objection revision round](#objection-revision-round) | Author's discretion | Work with participants to revise the text of the proposal to address paramount objections | -| [Approval](#approval) | N/A | Mark as approved and create issues to implement the proposal | -| [Tabling](#tabling) | N/A | Indicate that a proposal will not be implemented | - -## Process diagram - -```{mermaid} -flowchart TD - A[Proposal] --> B(Clarification Round) - B -->|Time: 3 days| C("Revision Round (if needed)") - C -->|Time: As needed/estimated by author| D(Decision round) - D -->|Time: 2 days| E("Objection revision (if needed)") - E -->|Time: As needed/estimated by author| F{Decision} - F -->|Insurmountable objections| G[Proposal tabled] - F -->|No objections| H[Proposal accepted] - G -->|New proposal needed| A - H --> I((End)) - G --> I -``` - -## Proposal requirements - -Project proposals and technical implementation plans should follow the formats -outlined in [the documentation for those processes](./docs/projects/README.md). -All proposals should include a summary of the -[purpose of the proposal](#purpose) and the problem(s) it attempts to address. - -Every proposal must include the following boilerplate text in the PR description -or at the top of the GitHub Discussion: - -```md -## Decision-making process - -For the purposes of this discussion, we will follow -[Openverse's decision-making model](https://docs.openverse.org/reference/consent_decision_making.html). -This process follows formalised steps with specific expectations of -participants. Before contributing, please read -[this document](https://docs.openverse.org/reference/consent_decision_making.html) -as well as -[Openverse's Code of Conduct](https://github.com/WordPress/openverse/blob/main/CODE_OF_CONDUCT.md). -The consent decision-making document linked above also includes instructions for -opting out of a decision discussion you do not wish to or cannot participate in. - -**If you've been asked to give input on this discussion but do not need to -participate in the full decision-making process**, please provide your -feedback/input however best fits the needs of the discussion. - -## Current round - -The discussion is currently in the **{Clarification, Revision, Decision, -Objection revision}** round. -``` - -## Round descriptions - -The following general guidelines apply to all rounds: - -- [Reactions](#reactions) may be shared at any time -- Proposal authors are not obligated to respond to every piece of feedback, - except for paramount objections. While there is an expectation that the author - will address outstanding questions, it isn't necessary to respond to every - non-paramount objection before moving on to subsequent rounds or marking the - proposal as approved. It is, of course, in the best interest of the project - and the proposal that as much clarity as possible is achieved. -- Authors may table a proposal at any time at their discretion. If the proposal - is tabled, discussion should not be expected to continue, but may, if there is - something important being discussed. -- Any round with a suggested length of time is subject to - [shortcutting as described below](#shortcutting-a-round) or to extension at - the discretion of the participants. - -### Clarification round - -The suggested length of this round is 3 business days. The goal of the -clarification round is to ensure everyone participating fully understands the -proposal. The focus of the round should be on asking clarifying questions and -uncovering hidden assumptions or gaps in the proposal. - -Some examples of helpful clarifying questions are: - -- "I don't understand y in the proposal, can you clarify what is meant by this?" -- "I think a gap exists in the proposed solution here [clarify where]. Can you - fill in the details in this area?" - -Participants should keep in mind that many objections can be restated as -questions. This helps promote good faith between participants and allows the -author to clarify things they might have missed in the initial draft of the -proposal. This does _not_ mean participants should delay sharing known paramount -objections. If you know that a proposed solution is impossible or illegal, -please do raise this concern as soon as possible. - -Note that the author does not have to respond to _every_ question. However, they -should keep them in mind during the revision round with the understanding that -the questions are shared in order to clarify the proposal. - -#### Purpose - -Proposals must all include an explicit "purpose". Often these are informed by -the needs of a particular project associated with the proposal or with a -requested discussion as the result of a retrospective or other self-feedback -mechanism. However, contributors may, at their discretion, raise proposals for -discussion that do not have prior conversations. In these cases, the question -round is also understood to include an evaluation and clarification of the -purpose of the proposal. For regularly requested proposals, however, the purpose -is taken to be accepted and should not be the focus of the discussion. - -### Revision round - -The goal of this round is to revise the proposal to include the clarifications -from the discussion in the previous round. What feedback is incorporated into -the document is at the discretion of the author. - -This round has no set time period. The author should use their discretion and -give an expected time when the revised version will be ready. The expected date -of completion for the revision is both for accountability (to prevent projects -from being stalled indefinitely) and for clarity of expectations for the other -participants in the process. If the author requires additional time beyond their -initial estimation, they should let the other participants know as soon as -possible, keeping in mind that other discussions may be stalled in the meantime. - -**No revisions should be made to the proposal before this point other than -grammatical or spelling corrections**. The reason for this is to allow the -clarification round to fully complete without the proposal changing during the -discussion. This allows clarification to happen fully without having to track -ongoing changes to the proposal. It also sets the expectation that revisions to -the proposal address the questions and reactions in full. This helps to minimise -the potentially "frantic" nature of a discussion that is happening about a -proposal document that is changing simultaneously with the discussion. - -### Decision round - -This round lasts for 2 business days. The goal of this round is to decide -whether the proposal can be implemented. Participants are asked to share -objections to the proposal if they do not think it can be implemented. - -There are two types of objections, paramount and non-paramount. Participants -must explicitly say which type of objection each of their objections falls -under. Objections are considered "paramount" only if: - -- They point to an issue that prevents the team from achieving its goals - (whether these are technical, community, or interpersonal). These issues can - also be said to "harm" the project or its contributors. -- The objection reveals something that is irreversible (or extremely difficult - to reverse) of which the participants are not at least "okay" with or "sure - of". For example, a proposal to switch to using MySQL when we're currently - invested heavily in Postgres would require significant time investment that - would be difficult to reverse. If the participants are not absolutely certain - that it is the best decision, then any objection to making the switch would be - paramount. - -During this round, as in the clarification round, the author should not modify -the text of the proposal. The focus of the author in this round should be to -clarify objections (especially paramount objections) and decide whether the -proposal can address them. This allows time for participants to fully digest the -proposal and raise all objections without further revision happening. -Participants are expected to help each other decide whether an objection is -paramount. Whether an objection is paramount can be questioned by the author, -but they should prefer to defer to the participants and trust their judgement. - -If there are no paramount objections then the process has finished and the -proposal is [approved](#approval). - -After the 2-day period, if the author does not think they can address the -paramount objections, then the proposal is [tabled](#tabling). For certain -proposals, this will be an unlikely outcome, in particular if the purpose of the -proposal is well-established and necessary for the project. However, sometimes a -paramount objection may be raised that requires completely re-writing the -proposal from the ground up. In that case, we will follow this process again -from the start with the new proposal, so we will end the process for the first -proposal at this round and wait for a new one to be raised. - -Regardless of the outcome, the author is responsible for completing -[the steps to finalise the discussion](#outcomes). - -### Objection revision round - -This round, similar to the previous revision round, lasts as long as the author -needs to completely address the paramount objections. The author will work with -the person who raised the objection to revise the proposal to address the issue -to resolution. The goal of this round is to reach a "good enough" middle ground -solution that either completely addresses the paramount objection or mitigates -the potential harm identified. - -As stated in the previous round's description, objection revision should only -happen if paramount objections can indeed be revised to remove the harm. If the -paramount objection involves a core issue of the proposal that cannot be -revised, then an entirely new proposal should be written, rather than the -"revision" replacing the entire existing proposal. It may be the case that in -the process of revision, the author of the proposal realises that they need to -"return to the drawing board". Please keep in mind that this is not a failure -and should be celebrated. So long as the objections were truly paramount, the -participants in the discussion and the author of the proposal have successfully -prevent long-term harm to the goals or people on the project. That is good news. - -Once the paramount objections are addressed, we will consider the proposal to be -accepted. The team as a whole can move on the next step of the project, whether -that is implementation planning or implementation itself. - -## Outcomes - -There are two possible outcomes for any proposal that follows this process: -approval or tabling. In both cases, the author is expected to: - -- Update the current round callout to indicate the outcome -- If the proposal is in a GitHub discussion, lock the discussion -- If the proposal is in a PR, merge the PR if approved or close it if tabled -- Move the associated card on the discussion dashboard to the appropriate column - -Further requirements specific to each outcome follow. - -### Approval - -Approval occurs once all paramount objections have been addressed and the author -is satisfied with the state of the proposal. At this point any necessary GitHub -issues should be created and linked to the proposal. - -### Tabling - -Tabling can occur in the following cases: - -- At any time, at the discretion of the author -- Before a proposal is written, if the team reneges on a requested discussion -- After a proposal is written, but before the discussion happens, if it is clear - the proposal will not fit the needs of the project -- During the decision round when insurmountable paramount objections are raised - -In the final case, the participants of the discussion are responsible for -deciding whether a new proposal should be requested. - -In any case, the proposal (if one exists) or the issue (if a proposal does not -exist) should be updated to reflect the tabled status and the reason why it was -tabled. It should also indicate whether a new proposal is requested. If a -proposal exists, the author is tasked with this responsibility. If no proposal -yet exists, then someone must volunteer to document the reasons for this -outcome. - -## Additional practices - -The following additional conventions will help our team make expedient decisions -while still following the formalised process laid out above. - -### Discussion Dashboard - -The -[discussion dashboard is implemented as a GitHub project](https://github.com/orgs/WordPress/projects/79/views/1) -for tracking the different rounds of a proposal. Proposal authors are expected -to correctly add and update proposals as they move through the different rounds -of discussion. This dashboard is used to -[help ensure we do not assign contributors to more than two discussions in parallel](#minimising-parallel-discussions), -so it is imperative that we maintain its accuracy. - -Each discussion should be tracked as a single card, with issues removed from the -"Pending proposal" column if a GitHub PR is opened. If a GitHub discussion is -used for the proposal, because those cannot be represented in GitHub project -boards, the issue should be used to track the status through the columns. - -This dashboard also serves as a record of decisions made on the team since the -dashboard's inception. Historical decisions that happened before the dashboard -started being used are not documented there. - -#### Column descriptions - -For the most part, the columns correspond 1-to-1 with rounds of the Openverse -consent decision-making process. However, the following columns are unique and -bear explanation: - -- "Proposal requested": This column is meant for requested proposals or - discussions for which no formal proposal yet exists. This column should be - populated by the issues that document the request. -- "Discussion pending": This column is meant for proposals that have been - written, but cannot yet start the decision-making process (likely due to - contributor unavailability). - -### Minimising parallel discussions - -In the past, Openverse maintainers have been prone to feeling overwhelmed or -over encumbered by too many ongoing discussions demanding their attention. The -following practices are meant to mitigate the chances of this happening by -creating tools and processes for keep the number of active discussions per -participant to 2 or fewer. - -#### Checking the dashboard - -Before requesting participation from specific people on a discussion, check the -[discussion dashboard](#discussion-dashboard) to ensure they're not already -involved in 2 ongoing discussions. If specific participants are required for a -given proposal (due to the relevance of their expertise in the proposal), then -you may open the proposal, but it should be left in the "pending discussion" -column. - -Tips for checking the dashboard and not accidentally over-encumbering people: - -- Check for discussions in the "pending discussion" column. If someone is - already assigned to discussions there, then know that any new discussions that - _must_ involve them will need to be triaged with the other discussion -- If a discussion could happen using the "lightening process", then you may be - able to pull people in who are waiting for a discussion to restart during the - revision round, even if they're already participating in the discussion - -In either case, it is still courteous to check with the individuals and make it -clear that they can push the discussion to someone else (provided they're not a -necessary subject-matter expert). - -#### Project level process discussions - -Because project level process discussions usually effect all maintainers and -sometimes other contributors, they naturally garner the expectation of -involvement from broader sets of people than technical discussions. In addition -to the guidelines above for general discussions, we need additional special -guidelines to ensure we do not become over encumbered with process discussions -specifically. In particular, retrospectives may give rise to several discussions -that need to happen at once. In these cases, and others where process -discussions begin to dominate the discussion backlog, we'll need to triage -discussions. If discussions truly need the involvement of the entire team, we -can follow two processes: - -1. Put (and prioritise) the discussions into the "proposal requested" column of - the discussion dashboard and only allow one team-wide discussion to occur at - a time. Limiting this to 1 allows other non-team-wide discussions to also - happen at the same time without flooding the discussion board with team-wide - discussions and halting other, smaller, often technical discussions. -2. Split the group into groups of three or four people who can participate in - different parts of the discussion. This is useful if there are multiple - time-sensitive discussions and could lead to synchronous "lightening process" - meetings to make faster decisions and reduce the ongoing discussion burden on - team members. Even in this case, limit to 1 ongoing team-wide process - discussion per group of contributors. This is less useful if everyone on the - team wishes to give input in the discussion, although people are free to - asynchronously give input before the fact. - -For both, we will aim to limit the process discussions to one discussion at a -time for any given team member. This is recommended to avoid discussion burn out -as I think I've observed process discussions feeling much heavier weight and -burdensome than technical discussions. It also makes sure there is still room -for team members to be involved in one other separate technical discussion and -feel like they can still focus on their other work duties. - -### Speeding up decision-making - -The base process should help the Openverse project make decisions more quickly -and effectively. However, the following additional practices are available to -help move things along at an even faster clip, if so desired. - -#### "Shortcutting" a round - -At any point during a round, any participant may say something along the lines -of "no (further) questions", "no reaction", or "no objection" in order to -short-cut their participation in the round. If all participants are finished -sharing their part in a given round, the author can choose to move to the next -round, even if the time period for the round has not been completed. This can be -particularly helpful for simpler discussions where the 2 business day -recommended time periods can feel overly slow. - -#### Optional, synchronous "lightening process" - -If all the participants of a particular discussion are able to participate in a -synchronous version of the process outlined above, they may elect to do so. This -can be particularly useful for relatively small but impactful decisions where -the 2 business day periods would unnecessarily drag the process out. In these -cases, participants should hold a synchronous conversation with the -understanding that someone will take notes for each round, recording the -questions, reactions, and any objections that arise. **The notes should be -shared afterwards in the original proposal venue and should include explicit -headings per round.** If necessary, the synchronous discussion can be broken -into two separate sections to allow time for the revision round after reactions -are shared. - -Even in these cases, however, the text of the proposal should still be written -in a GitHub PR or discussion and available for all participants to read _before_ -the lightening process. - -Differences in structure for the "lightening process" from the asynchronous -process are as follows: - -- We have a separate round for reactions. Therefore, the rounds are as follows: - 1. Clarification - 1. Reaction - 1. Revision - 1. Decision - 1. Objection revision -- Each round should have notes taken clearly documenting the feedback and - discussions for each (as appropriate). Priority should be given to questions - and objections that require revising the proposal. - -## How to follow the process in different settings - -The team has agreed to use GitHub for all discussions, with links shared on the -[WordPress Make Openverse blog](https://make.wordpress.org/openverse/) to help -visibility for certain discussions. - -There are two tools in GitHub that can be used for conducting a discussion: PRs -and GitHub Discussions. We do not use GitHub issues because they do not allow -for threading. - -### PRs - -GitHub PRs are used for project proposals, implementation planning RFCs, and -other proposals that will be documented as Markdown files in the repository. - -GitHub PRs have the following ways of interacting with comments: - -- Inline comments on specific lines of text or code - - These allow opening "threads" and can be resolved -- General PR comments -- Review comments - -Each of these can serve their own purposes: - -- Inline comments - - These are perfect to supplement the clarification and decision rounds. If a - request for clarification is about a specific part of the proposal (rather - than a more general clarification), participants can leave the question - directly on the relevant part of the proposal. Similarly, paramount - objections specific to one part of the proposal can be left as inline - comments attached to a review requesting changes. -- General PR comments - - For questions or non-paramount objections raised regarding the proposal in - general or for the reaction round. - - In addition to the PR description, the author of the PR will also create a - new top-level PR comment when a new round starts. -- Review comments - - These should be used in the decision round. Leave an approving review if you - have no paramount objections or "request changes" if you have a paramount - objection. Attach inline comments as needed in either case. - -### GitHub Discussions - -Because the format is slightly more limited than PRs, we will have a top-level -comment per round created by the author. Responses from participants should be -contained within the thread for each round. However, paramount objections during -the decision round, should be raised as individual threads. Still, the author -should still create a top-level comment closing the previous round and opening -the decision round. If the proposal goes into objection revision, the discussion -for addressing a given objection can happen in the accompanying thread. - -## Major differences from the original process - -Aside from being conducted primarily as an asynchronous process, Openverse's -consent decision-making process has the following major differences from the -Sociocratic model. - -### Reactions - -While the original process has a separate reactions round, in Openverse's -process, reactions can be shared at any time. Be careful to ensure that they're -not objections (which should, with few exceptions, be reserved for the objection -round). Examples of reactions are: - -- "I love this approach" -- "I like this proposal, but I don't understand X part of it yet" -- "I don't think this will work, but I left some questions to clarify the areas - I have concerns over" -- "I don't understand the underlying problem, so the solution seems too abstract - to me" -- "I don't think this solution will solve the problem as described" - -Note that these are not questions (they do not ask for clarification) nor are -they objections (they do not point to specific problems with the proposed -solution). - -### Removal of initial rounds - -Because our process is primarily asynchronous, because our decision-making -happens in public, and because the outcomes of our discussions are ultimately -documented in GitHub or other accessible venues, we can skip some of the initial -rounds. Specifically, the "consent to driver" and the "present the proposal" -rounds cannot work in the same way. Typically, the purpose of a proposal will -have been clarified through a previous discussion. Proposals raised without -prior "buy-in" from other contributors should be done so carefully, with the -understanding that participants may question the purpose and need for the -proposal. The presentation of a proposal happens implicitly when the GitHub PR -or discussion is opened to contain the proposal, so we do not need a special -step for this. diff --git a/documentation/reference/decision_making/additional_practices.md b/documentation/reference/decision_making/additional_practices.md new file mode 100644 index 00000000000..6f0bc16ce64 --- /dev/null +++ b/documentation/reference/decision_making/additional_practices.md @@ -0,0 +1,149 @@ +# Additional Practices + +The goal of the practices described in this document are to help the team adhere +to the general guidelines of the +[decision-making process](./process_description.md) without overburdening +participants with too many discussions. + +## Discussion Dashboard + +The +[discussion dashboard is implemented as a GitHub project](https://github.com/orgs/WordPress/projects/79/views/1) +for tracking the different rounds of a proposal. Proposal authors are expected +to correctly add and update proposals as they move through the different rounds +of discussion. This dashboard is used to +[help ensure we do not assign contributors to more than two discussions in parallel](#minimising-parallel-discussions), +so it is imperative that we maintain its accuracy. + +Each discussion should be tracked as a single card, with issues removed from the +"Pending proposal" column if a GitHub PR is opened. If a GitHub discussion is +used for the proposal, because those cannot be represented in GitHub project +boards, the issue should be used to track the status through the columns. + +This dashboard also serves as a record of decisions made on the team since the +dashboard's inception. Historical decisions that happened before the dashboard +started being used are not documented there. + +### Column descriptions + +For the most part, the columns correspond 1-to-1 with rounds of the Openverse +consent decision-making process. However, the following columns are unique and +bear explanation: + +- "Proposal requested": This column is meant for requested proposals or + discussions for which no formal proposal yet exists. This column should be + populated by the issues that document the request. +- "Discussion pending": This column is meant for proposals that have been + written, but cannot yet start the decision-making process (likely due to + contributor unavailability). + +## Minimising parallel discussions + +In the past, Openverse maintainers have been prone to feeling overwhelmed or +over encumbered by too many ongoing discussions demanding their attention. The +following practices are meant to mitigate the chances of this happening by +creating tools and processes for keep the number of active discussions per +participant to 2 or fewer. + +### Checking the dashboard + +Before requesting participation from specific people on a discussion, check the +[discussion dashboard](#discussion-dashboard) to ensure they're not already +involved in 2 ongoing discussions. If specific participants are required for a +given proposal (due to the relevance of their expertise in the proposal), then +you may open the proposal, but it should be left in the "pending discussion" +column. + +Tips for checking the dashboard and not accidentally over-encumbering people: + +- Check for discussions in the "pending discussion" column. If someone is + already assigned to discussions there, then know that any new discussions that + _must_ involve them will need to be triaged with the other discussion +- If a discussion could happen using the "lightening process", then you may be + able to pull people in who are waiting for a discussion to restart during the + revision round, even if they're already participating in the discussion + +In either case, it is still courteous to check with the individuals and make it +clear that they can push the discussion to someone else (provided they're not a +necessary subject-matter expert). + +### Project level process discussions + +Because project level process discussions usually effect all maintainers and +sometimes other contributors, they naturally garner the expectation of +involvement from broader sets of people than technical discussions. In addition +to the guidelines above for general discussions, we need additional special +guidelines to ensure we do not become over encumbered with process discussions +specifically. In particular, retrospectives may give rise to several discussions +that need to happen at once. In these cases, and others where process +discussions begin to dominate the discussion backlog, we'll need to triage +discussions. If discussions truly need the involvement of the entire team, we +can follow two processes: + +1. Put (and prioritise) the discussions into the "proposal requested" column of + the discussion dashboard and only allow one team-wide discussion to occur at + a time. Limiting this to 1 allows other non-team-wide discussions to also + happen at the same time without flooding the discussion board with team-wide + discussions and halting other, smaller, often technical discussions. +2. Split the group into groups of three or four people who can participate in + different parts of the discussion. This is useful if there are multiple + time-sensitive discussions and could lead to synchronous "lightening process" + meetings to make faster decisions and reduce the ongoing discussion burden on + team members. Even in this case, limit to 1 ongoing team-wide process + discussion per group of contributors. This is less useful if everyone on the + team wishes to give input in the discussion, although people are free to + asynchronously give input before the fact. + +For both, we will aim to limit the process discussions to one discussion at a +time for any given team member. This is recommended to avoid discussion burn out +as I think I've observed process discussions feeling much heavier weight and +burdensome than technical discussions. It also makes sure there is still room +for team members to be involved in one other separate technical discussion and +feel like they can still focus on their other work duties. + +## Speeding up decision-making + +The base process should help the Openverse project make decisions more quickly +and effectively. However, the following additional practices are available to +help move things along at an even faster clip, if so desired. + +### "Shortcutting" a round + +At any point during a round, any participant may say something along the lines +of "no (further) questions", "no reaction", or "no objection" in order to +short-cut their participation in the round. If all participants are finished +sharing their part in a given round, the author can choose to move to the next +round, even if the time period for the round has not been completed. This can be +particularly helpful for simpler discussions where the 2 business day +recommended time periods can feel overly slow. + +### Optional, synchronous "lightening process" + +If all the participants of a particular discussion are able to participate in a +synchronous version of the process outlined above, they may elect to do so. This +can be particularly useful for relatively small but impactful decisions where +the 2 business day periods would unnecessarily drag the process out. In these +cases, participants should hold a synchronous conversation with the +understanding that someone will take notes for each round, recording the +questions, reactions, and any objections that arise. **The notes should be +shared afterwards in the original proposal venue and should include explicit +headings per round.** If necessary, the synchronous discussion can be broken +into two separate sections to allow time for the revision round after reactions +are shared. + +Even in these cases, however, the text of the proposal should still be written +in a GitHub PR or discussion and available for all participants to read _before_ +the lightening process. + +Differences in structure for the "lightening process" from the asynchronous +process are as follows: + +- We have a separate round for reactions. Therefore, the rounds are as follows: + 1. Clarification + 1. Reaction + 1. Revision + 1. Decision + 1. Objection revision +- Each round should have notes taken clearly documenting the feedback and + discussions for each (as appropriate). Priority should be given to questions + and objections that require revising the proposal. diff --git a/documentation/reference/decision_making/index.md b/documentation/reference/decision_making/index.md new file mode 100644 index 00000000000..139ec1da2d1 --- /dev/null +++ b/documentation/reference/decision_making/index.md @@ -0,0 +1,15 @@ +# Openverse Decision-Making Process + +This process is loosely based on the Sociocratic "consent decision-making" +model, but is heavily adapted for an asynchronous context. The purpose of this +process is to help contributors to the Openverse project make expedient +decisions. That is, decisions that are both "good enough for now" and also made +quickly. In many ways, this process is a refinement on what was already being +practised, but with clearer expectations about time and feedback expression. + +```{toctree} +:maxdepth: 1 + +process_description +additional_practices +``` diff --git a/documentation/reference/decision_making/process_description.md b/documentation/reference/decision_making/process_description.md new file mode 100644 index 00000000000..cd05fdcfff4 --- /dev/null +++ b/documentation/reference/decision_making/process_description.md @@ -0,0 +1,187 @@ +# Process Description + +## Terms + +- "Participants": The author, all requested reviewers, and any additional + discussion participants. +- "Problem": A problematic aspect of the proposed solution, whether objective or + subjective. +- "Objective problem": A problem that does not depend on an individual's + perspective, i.e., something illegal, impossible, or too expensive. +- "Subjective problem": A problem regarding a matter of preference, e.g., a + choice between two roughly equivalent and usable tools. +- "Blocker": A problem with a proposed solution that would cause lasting harm to + the project or its contributors. +- "Fixable blocker": A blocker that can be addressed by revising the proposal. +- "Unworkable blocker": A blocker that cannot be addressed by revising the + proposal. In other words, an issue that requires an entirely new proposal to + be addressed. + +## Process Overview + +The process is split into a series of rounds with broad expectations explained +below. Each step has a particular goal that participants should keep in mind. +The decision and continued revision round can repeat as many times as needed, at +the discretion of the participants. + +| Round | Suggested span | Goal | +| ----------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------ | +| [Clarification round](#clarification-round) | 5 days | Clarify the proposal; share initial reactions | +| [Revision round](#revision-round) | Author's discretion | Update the text of the proposal to reflect the outcome of the previous round | +| [Decision round](#decision-round) | 3 days | Decide whether the proposal can be implemented as is | +| [Continued revision round](#objection-revision-round) | Author's discretion | Work with participants to revise the text of the proposal to address blocking issues | +| [Approval](#approval) | N/A | Mark as approved and create issues to implement the proposal | +| [Tabling](#tabling) | N/A | Indicate that a proposal will not be implemented | + +### Time Spans + +The suggested spans are just that: suggestions. If a particular proposal needs +more time for any reason, participants should note that and extend the round +duration. If reviewers are taken away from reviewing a proposal due to +extenuating circumstances like a production incident they need to be involved +in, they should note their unavailability on the discussion as soon as possible. +This expectation to notify of course does not apply if someone is taken away to +deal with life circumstances or other unexpected time AFK. + +In any case, participants will work together to decide whether the proposal can +wait or if another person should be requested to replace the unavailable person. + +Additionally, participants should try to maintain accountability to the +agreed-upon time spans. This means responding in a timely manner within the +window provided, understanding that authors will also need time to respond to +feedback, and following the practice described above to make explicit when they +will not be able to do so. + +### Diagram + +```{mermaid} +flowchart TD + A[Proposal] --> B(Clarification Round) + B -->|Time: 3 days| C("Revision Round (if needed)") + C -->|Time: As needed/estimated by author| D(Decision Round) + D -.->|Fixable blocking issues identified| E + E("Continued Revision Round (if needed)") + D -.->|No blocking issues identified| H + E --> D + D -.->|Unworkable blocking issues identified| G + G[Proposal tabled] -->|New proposal needed| A + H[Proposal approved] --> I((End)) +``` + +## Round Descriptions + +> **Note** +> +> While each round includes discussion guidelines and a description of purpose, +> these are flexible. Participants should use their discretion and should adapt +> the process as needed for any given proposal. If a blocker is apparent at the +> start of a discussion, do not wait for the decision round to share it. If a +> solution is known to be illegal or impossible, share that as early as +> possible. Additionally, if a proposal document has a structural issue that +> belies clarification, authors may revise to fix the proposal as soon as the +> problem is identified. + +### Clarification Round + +The goal of this round is for participants to clarify the proposed solution and +share their initial thoughts and feelings about the proposal. We especially +encourage reviewers to look for opportunities to share explicit praise where it +is due. The broad focus should be on ensuring all participants understand what +is being proposed and why other potential solutions, if any reasonable ones +exist, were not chosen. By ensuring participants understand a proposal and that +the author has a chance to revise any initial problems identified during +clarification, we hope to cultivate an increased sense of trust: both that +reviewers are reviewing in good faith and that the author's work is respected +and understood to be the best attempt at proposing a solution to the problem. + +During this round authors should refrain as much as possible from making large +changes to the proposal other than editorial/proofreading ones. This is to help +minimise confusion caused by a proposal that is changing while also being +reviewed for clarification. + +#### Purpose + +Proposals must all include an explicit "purpose". Often these are informed by +the needs of a particular project associated with the proposal or with a +requested discussion as the result of a retrospective or other self-feedback +mechanism. However, contributors may, at their discretion, raise proposals for +discussion that do not have prior conversations. In these cases, the +clarification round is also understood to include an evaluation and +clarification of the purpose of the proposal. For regularly requested proposals, +however, the purpose is taken to be accepted and should not be the focus of the +discussion. + +### Revision Round + +The goal of this round is for authors to incorporate the feedback received in +the clarification round. At this time, any changes can be made to the proposal +document. + +When the round starts, the author should share how long they will need to finish +revising the document. This helps give clear expectations for reviewers for when +they will need to return to the discussion and also establishes accountability +on the part of the author. Together these help prevent discussions from dragging +on or having an indefinite "slump" during revision. + +### Decision Round + +The goal of this round is for the participants to decide whether the proposal +can be implemented in its current form. The focus of this round should be to +carefully consider any problems present with the proposal and decide whether +they are blockers or whether they can be iterated on after the initial +implementation. If an issue is a blocker, then reviewers should request changes +to address the issue, if it can be addressed. If the blocking issue cannot be +addressed (it is "unworkable"), then the proposal is tabled, though this should +be rare. Participants should all work together to help identify whether an issue +is truly a blocker or whether it is something that can be iterated on. Objective +problems should be given priority, whereas addressing subjective problems should +err on the side of avoiding the need for large revisions. If a proposal is +founded upon the usage of one tool, but another equivalent tool is also +available, it is up to the author whether they feel it is worth reworking the +proposal to use the other tool to appease the preference of the reviewer. + +The idea behind this specific structure is two-fold: + +- It acknowledges that Openverse maintainers are capable contributors and more + often than propose solutions that are workable, even if they sometimes need + revisions +- It makes explicit the expectation that we are looking for "good enough for + now" solutions that can be iterated and improved on afterwards + +Both of these help decision-making go faster, while also carefully identifying +what aspects of a proposal may need special attention either during +implementation or after the fact. Both of these are also, however, not steadfast +rules. Everyone makes mistakes and everyone can miss big or small details of a +problem that lead them down the wrong path. Working together as a team, all the +participants are tasked with deciding whether a solution is feasible and finding +ways to resolve blockers. + +### Continued Revision Round + +If fixable blocking problems are identified during the decision round, the +author and participants should work together to revise the proposal to address +the problem so that it is no longer a blocker. This can be done either by +changing the proposal so that the problem no longer exists at all, or so that +the potential harm caused by the problem is mitigated. In other words, the +problem could still exist (whether objectively or subjectively), but the harm +caused by it is either no longer possible or sufficient guardrails or safety +measures have been taken to mitigate and address the harm or make it reversible. + +After the revision is complete, the proposal goes back to the decision round. +The decision round and the continued revision round can repeat as many times as +needed until a proposal no longer has blockers. + +### Proposal Approval + +Proposals are approved when the requested reviewers have voiced approval and +there are no outstanding blockers. + +At this stage, authors will create any new milestones or issues to track the +work needed to implement the accepted solution. Milestones should be linked in +the proposal text. + +### Proposal Tabling + +Proposals are tabled when unworkable blockers are identified. In cases where a +proposal was requested as part of a project, a new proposal should be requested +that approaches the problem in a new way to avoid causing the same problems. diff --git a/documentation/reference/index.md b/documentation/reference/index.md index 0b00a4cbb9e..36d4fcfe46e 100644 --- a/documentation/reference/index.md +++ b/documentation/reference/index.md @@ -1,10 +1,10 @@ # Reference ```{toctree} -:maxdepth: 1 +:maxdepth: 3 github_contribution_practices -consent_decision_making +decision_making/index dev_flow api/index frontend/index From e7bbdc997782ee136524735e535bdd9329b952f0 Mon Sep 17 00:00:00 2001 From: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> Date: Fri, 31 Mar 2023 12:15:41 +1100 Subject: [PATCH 13/14] Add current round callout to additional practices and further simplify language --- .../decision_making/additional_practices.md | 73 ++++++++++--------- .../decision_making/process_description.md | 45 ++++++++---- 2 files changed, 70 insertions(+), 48 deletions(-) diff --git a/documentation/reference/decision_making/additional_practices.md b/documentation/reference/decision_making/additional_practices.md index 6f0bc16ce64..b38d4b91eba 100644 --- a/documentation/reference/decision_making/additional_practices.md +++ b/documentation/reference/decision_making/additional_practices.md @@ -5,6 +5,28 @@ to the general guidelines of the [decision-making process](./process_description.md) without overburdening participants with too many discussions. +## Current-round Call Out + +In the PR description or top-post of a GitHub discussion, discussion leaders +should include the following text: + +```md +This discussion is following the Openverse decision-making process. Information +about this process can be found +[on the Openverse documentation site](https://docs.openverse.org/reference/decision_making.html). +Requested reviewers or participants will be following this process. If you are +being asked to give input on a specific detail, you do not need to familiarise +yourself with the process and follow it. + +## Current Round + +This discussion is currently in the **{Clarification, Revision, Decision, +Continued Revision} round**. +``` + +When a round ends, discussion leaders should leave a comment announcing the next +round along with the length of time allotted for it. + ## Discussion Dashboard The @@ -59,9 +81,10 @@ Tips for checking the dashboard and not accidentally over-encumbering people: - Check for discussions in the "pending discussion" column. If someone is already assigned to discussions there, then know that any new discussions that _must_ involve them will need to be triaged with the other discussion -- If a discussion could happen using the "lightening process", then you may be - able to pull people in who are waiting for a discussion to restart during the - revision round, even if they're already participating in the discussion +- If a discussion could happen synchronously (if all participants have time + available), then you may be able to pull people in who are waiting for a + discussion to restart during the revision round, even if they're already + participating in the discussion In either case, it is still courteous to check with the individuals and make it clear that they can push the discussion to someone else (provided they're not a @@ -110,40 +133,24 @@ help move things along at an even faster clip, if so desired. ### "Shortcutting" a round At any point during a round, any participant may say something along the lines -of "no (further) questions", "no reaction", or "no objection" in order to -short-cut their participation in the round. If all participants are finished -sharing their part in a given round, the author can choose to move to the next -round, even if the time period for the round has not been completed. This can be -particularly helpful for simpler discussions where the 2 business day -recommended time periods can feel overly slow. +of "no (further) discussion needed on my part" in order to short-cut their +participation in the round. If all participants are finished sharing their part +in a given round, the author can choose to move to the next round, even if the +time period for the round has not been completed. This can be particularly +helpful for simpler discussions. -### Optional, synchronous "lightening process" +### Going synchronous If all the participants of a particular discussion are able to participate in a -synchronous version of the process outlined above, they may elect to do so. This -can be particularly useful for relatively small but impactful decisions where -the 2 business day periods would unnecessarily drag the process out. In these -cases, participants should hold a synchronous conversation with the -understanding that someone will take notes for each round, recording the -questions, reactions, and any objections that arise. **The notes should be -shared afterwards in the original proposal venue and should include explicit -headings per round.** If necessary, the synchronous discussion can be broken -into two separate sections to allow time for the revision round after reactions -are shared. +synchronous decision-making process, they may elect to do so. This can be +particularly useful for relatively small but impactful decisions where the +discussion periods would unnecessarily drag the process out. In these cases, +participants should hold a synchronous conversation with the understanding that +someone will take notes for each round, recording the feedback shared. **The +notes should be shared afterwards in the original proposal venue and should +include explicit headings per round.** If necessary, the synchronous discussion +can be broken into two separate sections to allow time for revision. Even in these cases, however, the text of the proposal should still be written in a GitHub PR or discussion and available for all participants to read _before_ the lightening process. - -Differences in structure for the "lightening process" from the asynchronous -process are as follows: - -- We have a separate round for reactions. Therefore, the rounds are as follows: - 1. Clarification - 1. Reaction - 1. Revision - 1. Decision - 1. Objection revision -- Each round should have notes taken clearly documenting the feedback and - discussions for each (as appropriate). Priority should be given to questions - and objections that require revising the proposal. diff --git a/documentation/reference/decision_making/process_description.md b/documentation/reference/decision_making/process_description.md index cd05fdcfff4..fbcbe551964 100644 --- a/documentation/reference/decision_making/process_description.md +++ b/documentation/reference/decision_making/process_description.md @@ -14,7 +14,7 @@ the project or its contributors. - "Fixable blocker": A blocker that can be addressed by revising the proposal. - "Unworkable blocker": A blocker that cannot be addressed by revising the - proposal. In other words, an issue that requires an entirely new proposal to + proposal. In other words, a problem that requires an entirely new proposal to be addressed. ## Process Overview @@ -24,14 +24,14 @@ below. Each step has a particular goal that participants should keep in mind. The decision and continued revision round can repeat as many times as needed, at the discretion of the participants. -| Round | Suggested span | Goal | -| ----------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------ | -| [Clarification round](#clarification-round) | 5 days | Clarify the proposal; share initial reactions | -| [Revision round](#revision-round) | Author's discretion | Update the text of the proposal to reflect the outcome of the previous round | -| [Decision round](#decision-round) | 3 days | Decide whether the proposal can be implemented as is | -| [Continued revision round](#objection-revision-round) | Author's discretion | Work with participants to revise the text of the proposal to address blocking issues | -| [Approval](#approval) | N/A | Mark as approved and create issues to implement the proposal | -| [Tabling](#tabling) | N/A | Indicate that a proposal will not be implemented | +| Round | Suggested span | Goal | +| ----------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------- | +| [Clarification round](#clarification-round) | 5 days | Clarify the proposal; share initial thoughts | +| [Revision round](#revision-round) | Author's discretion | Update the text of the proposal to reflect the outcome of the previous round | +| [Decision round](#decision-round) | 3 days | Decide whether the proposal can be implemented as is | +| [Continued revision round](#continued-revision-round) | Author's discretion | Work with participants to revise the text of the proposal to address blockers | +| [Approval](#approval) | N/A | Mark as approved and create issues to implement the proposal | +| [Tabling](#tabling) | N/A | Indicate that a proposal will not be implemented | ### Time Spans @@ -57,13 +57,13 @@ will not be able to do so. ```{mermaid} flowchart TD A[Proposal] --> B(Clarification Round) - B -->|Time: 3 days| C("Revision Round (if needed)") + B -->|"Time: ~5 days"| C("Revision Round (if needed)") C -->|Time: As needed/estimated by author| D(Decision Round) - D -.->|Fixable blocking issues identified| E + D -.->|Fixable blockers identified| E E("Continued Revision Round (if needed)") - D -.->|No blocking issues identified| H + D -.->|No blockers identified| H E --> D - D -.->|Unworkable blocking issues identified| G + D -.->|Unworkable blockers identified| G G[Proposal tabled] -->|New proposal needed| A H[Proposal approved] --> I((End)) ``` @@ -129,8 +129,10 @@ The goal of this round is for the participants to decide whether the proposal can be implemented in its current form. The focus of this round should be to carefully consider any problems present with the proposal and decide whether they are blockers or whether they can be iterated on after the initial -implementation. If an issue is a blocker, then reviewers should request changes -to address the issue, if it can be addressed. If the blocking issue cannot be +implementation. If further clarification is needed about an aspect of the +proposal that could cause harm, that is automatically considered to be a +blocker. If problem is a blocker, then reviewers should request changes to +address the issue, if it can be addressed. If the blocking issue cannot be addressed (it is "unworkable"), then the proposal is tabled, though this should be rare. Participants should all work together to help identify whether an issue is truly a blocker or whether it is something that can be iterated on. Objective @@ -156,6 +158,19 @@ problem that lead them down the wrong path. Working together as a team, all the participants are tasked with deciding whether a solution is feasible and finding ways to resolve blockers. +The suggested time span for the decision round is shorter for two reasons: + +1. To encourage front-loading discussion during the clarification round +1. To acknowledge that the goal of the decision round is to decide whether the + proposal can be implemented and iterated on or whether it has blockers + +The decision round isn't necessarily another discussion round, aside from +deliberating about whether certain problems are blockers or not. Three days is +the suggested span because it allows time for at least one back and forth +between author and reviewers to decide whether problems are blockers. Further +discussion about the problems should continue during the subsequent revision +round between the person who identified the blocker and the proposal author. + ### Continued Revision Round If fixable blocking problems are identified during the decision round, the From 5e22c4809a1d498ca381234596e39afdcec32359 Mon Sep 17 00:00:00 2001 From: sarayourfriend <24264157+sarayourfriend@users.noreply.github.com> Date: Fri, 31 Mar 2023 13:21:28 +1100 Subject: [PATCH 14/14] Use consistent heading casing and add back how to use docs --- .../decision_making/additional_practices.md | 8 +-- .../reference/decision_making/how_to_use.md | 49 +++++++++++++++++++ .../reference/decision_making/index.md | 3 +- .../decision_making/process_description.md | 20 ++++---- documentation/reference/index.md | 2 +- 5 files changed, 66 insertions(+), 16 deletions(-) create mode 100644 documentation/reference/decision_making/how_to_use.md diff --git a/documentation/reference/decision_making/additional_practices.md b/documentation/reference/decision_making/additional_practices.md index b38d4b91eba..f91f4942150 100644 --- a/documentation/reference/decision_making/additional_practices.md +++ b/documentation/reference/decision_making/additional_practices.md @@ -1,11 +1,11 @@ -# Additional Practices +# Additional practices The goal of the practices described in this document are to help the team adhere to the general guidelines of the [decision-making process](./process_description.md) without overburdening participants with too many discussions. -## Current-round Call Out +## Current-round call out In the PR description or top-post of a GitHub discussion, discussion leaders should include the following text: @@ -18,7 +18,7 @@ Requested reviewers or participants will be following this process. If you are being asked to give input on a specific detail, you do not need to familiarise yourself with the process and follow it. -## Current Round +## Current round This discussion is currently in the **{Clarification, Revision, Decision, Continued Revision} round**. @@ -27,7 +27,7 @@ Continued Revision} round**. When a round ends, discussion leaders should leave a comment announcing the next round along with the length of time allotted for it. -## Discussion Dashboard +## Discussion dashboard The [discussion dashboard is implemented as a GitHub project](https://github.com/orgs/WordPress/projects/79/views/1) diff --git a/documentation/reference/decision_making/how_to_use.md b/documentation/reference/decision_making/how_to_use.md new file mode 100644 index 00000000000..e7796f99652 --- /dev/null +++ b/documentation/reference/decision_making/how_to_use.md @@ -0,0 +1,49 @@ +# How to follow the process in different settings + +The team has agreed to use GitHub for all discussions, with links shared on the +[WordPress Make Openverse blog](https://make.wordpress.org/openverse/) to help +visibility for certain discussions. + +There are two tools in GitHub that can be used for conducting a discussion: PRs +and GitHub Discussions. We do not use GitHub issues because they do not allow +for threading. + +## PRs + +GitHub PRs are used for project proposals, implementation planning RFCs, and +other proposals that will be documented as Markdown files in the repository. + +GitHub PRs have the following ways of interacting with comments: + +- Inline comments on specific lines of text or code + - These allow opening "threads" and can be resolved +- General PR comments +- Review comments + +Each of these can serve their own purposes: + +- Inline comments + - These are perfect to supplement the clarification and decision rounds. If is + needed for a specific part of the proposal (rather than a more general + clarification), participants can leave their comments directly on the + relevant part of the proposal. Similarly, blockers specific to one part of + the proposal can be left as inline comments attached to a review requesting + changes. +- General PR comments + - For comments about the proposal in general like broad questions or problems. + - In addition to the PR description, the author of the PR will also create a + new top-level PR comment when a new round starts. +- Review comments + - These should be used in the decision round. Leave an approving review if you + have no blockers or "request changes" if you have a blocker. Attach inline + comments as needed in either case. + +## GitHub Discussions + +Because the format is slightly more limited than PRs, we will have a top-level +comment per round created by the author. Responses from participants should be +contained within the thread for each round. However, blockers during the +decision round should be raised as individual threads. The author will create a +top-level comment closing the previous round and opening the subsequent round. +If the proposal goes into continued revision, the discussion for addressing a +blocker can happen in the thread identifying the blocker. diff --git a/documentation/reference/decision_making/index.md b/documentation/reference/decision_making/index.md index 139ec1da2d1..a9816820181 100644 --- a/documentation/reference/decision_making/index.md +++ b/documentation/reference/decision_making/index.md @@ -8,8 +8,9 @@ quickly. In many ways, this process is a refinement on what was already being practised, but with clearer expectations about time and feedback expression. ```{toctree} -:maxdepth: 1 +:maxdepth: 2 process_description additional_practices +how_to_use ``` diff --git a/documentation/reference/decision_making/process_description.md b/documentation/reference/decision_making/process_description.md index fbcbe551964..c072a5da4c4 100644 --- a/documentation/reference/decision_making/process_description.md +++ b/documentation/reference/decision_making/process_description.md @@ -1,4 +1,4 @@ -# Process Description +# Process description ## Terms @@ -17,7 +17,7 @@ proposal. In other words, a problem that requires an entirely new proposal to be addressed. -## Process Overview +## Process overview The process is split into a series of rounds with broad expectations explained below. Each step has a particular goal that participants should keep in mind. @@ -33,7 +33,7 @@ the discretion of the participants. | [Approval](#approval) | N/A | Mark as approved and create issues to implement the proposal | | [Tabling](#tabling) | N/A | Indicate that a proposal will not be implemented | -### Time Spans +### Time spans The suggested spans are just that: suggestions. If a particular proposal needs more time for any reason, participants should note that and extend the round @@ -68,7 +68,7 @@ flowchart TD H[Proposal approved] --> I((End)) ``` -## Round Descriptions +## Round descriptions > **Note** > @@ -81,7 +81,7 @@ flowchart TD > belies clarification, authors may revise to fix the proposal as soon as the > problem is identified. -### Clarification Round +### Clarification round The goal of this round is for participants to clarify the proposed solution and share their initial thoughts and feelings about the proposal. We especially @@ -111,7 +111,7 @@ clarification of the purpose of the proposal. For regularly requested proposals, however, the purpose is taken to be accepted and should not be the focus of the discussion. -### Revision Round +### Revision round The goal of this round is for authors to incorporate the feedback received in the clarification round. At this time, any changes can be made to the proposal @@ -123,7 +123,7 @@ they will need to return to the discussion and also establishes accountability on the part of the author. Together these help prevent discussions from dragging on or having an indefinite "slump" during revision. -### Decision Round +### Decision round The goal of this round is for the participants to decide whether the proposal can be implemented in its current form. The focus of this round should be to @@ -171,7 +171,7 @@ between author and reviewers to decide whether problems are blockers. Further discussion about the problems should continue during the subsequent revision round between the person who identified the blocker and the proposal author. -### Continued Revision Round +### Continued revision round If fixable blocking problems are identified during the decision round, the author and participants should work together to revise the proposal to address @@ -186,7 +186,7 @@ After the revision is complete, the proposal goes back to the decision round. The decision round and the continued revision round can repeat as many times as needed until a proposal no longer has blockers. -### Proposal Approval +### Proposal approval Proposals are approved when the requested reviewers have voiced approval and there are no outstanding blockers. @@ -195,7 +195,7 @@ At this stage, authors will create any new milestones or issues to track the work needed to implement the accepted solution. Milestones should be linked in the proposal text. -### Proposal Tabling +### Proposal tabling Proposals are tabled when unworkable blockers are identified. In cases where a proposal was requested as part of a project, a new proposal should be requested diff --git a/documentation/reference/index.md b/documentation/reference/index.md index 36d4fcfe46e..48e2aa7d454 100644 --- a/documentation/reference/index.md +++ b/documentation/reference/index.md @@ -1,7 +1,7 @@ # Reference ```{toctree} -:maxdepth: 3 +:maxdepth: 2 github_contribution_practices decision_making/index