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 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.