Add consent decision-making process documentation

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"

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"}

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

documentation/reference/decision_making/additional_practices.md

@@ -0,0 +1,156 @@
+# 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
+
+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
+[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 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
+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) 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.
+
+### Going synchronous
+
+If all the participants of a particular discussion are able to participate in a
+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.

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.

documentation/reference/decision_making/index.md

@@ -0,0 +1,16 @@
+# 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: 2
+
+process_description
+additional_practices
+how_to_use
+```