Add guide to PR statuses and labels

source/developers/references/developer_guide/process/FAQ-about-pull-requests.rst

@@ -6,6 +6,9 @@ Community contributions, in the form of pull requests, go through a process
 shepherded by the `Community Contribution Project Managers`_. These
 contributions are sometimes referred to as "OSPRs" (open source pull requests).
 
+See the :doc:`pull-request-statuses` if you're looking for more information about
+what the various statuses and labels of your pull request (PR) mean.
+
 .. contents::
  :local:
  :depth: 1
@@ -101,8 +104,9 @@ As pull requests move through the process, the Community Project Managers update
 the PR's status, and use labels to denote different aspects / states of the PR.
 This helps reviewers better understand what action(s) are needed, and by who.
 
-A breakdown of these statuses and labels can be found **TODO** here for reference (though,
-PR authors are not responsible for updating PR status or labels).
+A breakdown of these statuses and labels can be found at the
+:doc:`pull-request-statuses` for reference (though, PR authors are not
+responsible for updating PR status or labels).
 
 On the right-hand side of the PR, you'll be able to see the status of your pull
 request, the Community PM responsible for the PR, and the last date the

source/developers/references/developer_guide/process/index.rst

@@ -11,4 +11,5 @@ Contributing to the Open edX Project
     contributor
     code-considerations
     FAQ-about-pull-requests
+    pull-request-statuses
     core-contributors

source/developers/references/developer_guide/process/pull-request-statuses.rst

@@ -0,0 +1,125 @@
+=========================
+Pull Request Status Guide
+=========================
+
+---------------------------
+Contribution Board Statuses
+---------------------------
+
+.. list-table:: Title
+   :widths: 30 70
+   :header-rows: 1
+
+   * - **Status**
+     - **Description(s)**
+
+   * - **Needs Triage**
+     - A bot automatically places open-source contributions in this status and
+       labels them as such. The Community Project Managers triage PRs from here
+   * - **Needs Tests Run, or CLA Signed**
+     - 
+         * If the author has never contributed to a particular repo, they need
+           authorization to run tests on the pull request [enabling tests is
+           currently handled by Axim].
+         * If the author has never contributed to the Open edX project before,
+           they need to fill out a CLA form.
+   * - **In Product Review**
+     - Actively being reviewed by Product (only applies to PRs labeled as
+       needing product review) - pull requests needing product review must have
+       product approval before continuing through the process
+   * - **Waiting for Author**
+     - 
+         * The PR is actively in progress
+         * The author needs to address questions, feedback, rebase, etc.
+         * The PR is still in a draft state
+
+   * - **Blocked**
+     - Blocked by other pull requests / work. There should be context within the
+       PR for why it's blocked
+   * - **Ready for Review**
+     - 
+         * Ready for review by maintainer or repo owner
+         * All checks have passed and are green (including CLA)
+         * The owning / maintaining team has been asked to review
+
+   * - **Scheduled for Eng Review**
+     - The reviewing team has scheduled to review this in an upcoming sprint,
+       has assigned themselves to review
+
+   * - **In Eng Review**
+     - Actively being reviewed by Engineering.
+
+   * - **Ready to Merge**
+     - 
+         * Reviews are complete
+         * Tests are green
+         * No conflicts, and branch is not out-of-date
+         * Changes and feedback have been addressed
+         * Reviewer has approved
+
+   * - **Done**
+     - Merged/Closed
+
+-------------------------
+Contribution Board Labels
+-------------------------
+
+**Note**: Depending on the situation, more than one of these labels may be on a
+pull request at the same time. Though some may seem repetitive of the status
+columns, the PRs might have several things going on simultaneously, so these
+labels compliment the above board statuses.
+
+For example, a pull request could be “In Eng Review” on the Contributions board,
+but be tagged with the “Waiting for Author” and/or “Changes Requested” label if
+the author needs to take actions related to feedback.
+
+.. list-table:: Title
+   :widths: 30 70
+   :header-rows: 1
+
+   * - **Label**
+     - **Description**
+
+   * - .. image:: /_images/pr_label_open-source-contribution.png
+     - Automatically added by a bot to PRs coming from the community (not from Axim or 2U).
+
+   * - .. image:: /_images/pr_label_backport.png
+     - Denotes that the PR backports a change from main to a named release.
+
+   * - .. image:: /_images/pr_label_blocked_by_other_work.png
+     - Another way to notate that the PR is blocked. It should say in the PR why
+       the work is blocked.
+   * - .. image:: /_images/pr_label_changes_requested.png
+     - The reviewer(s) have taken a look at the PR and requested the author make changes.
+
+   * - .. image:: /_images/pr_label_closed-inactivity.png
+     - Closed due to PR being abandoned.
+
+   * - .. image:: /_images/pr_label_core_contributor.png
+     - Denotes that a :doc:`Core Contributor <core-contributors>` is the author
+       of the pull request.
+   * - .. image:: /_images/pr_label_inactive.png
+     - Used when the author has been unresponsive for an extended period of
+       time. The Community Projects Managers will typically give a final comment
+       to the author alerting them the pull request may need to be closed due to
+       inactivity. If there is still no response from the author, the PR will be
+       closed shortly after.
+
+   * - .. image:: /_images/pr_label_needs_test_run.png
+     - This means an author has not contributed to a particular repo before and
+       needs authorization to be able to run tests on the PR. Currently, test
+       authorization is handled by Axim.
+
+   * - .. image:: /_images/pr_label_product_review.png
+     - Indicates that a PR requires Product Review. Product review is done
+       either before code is written, or before Engineering review if the PR is
+       already in-progress.
+
+   * - .. image:: /_images/pr_label_waiting_for_eng_review.png
+       .. image:: /_images/pr_label_needs_maintainer_attention.png
+     - Used to alert reviewers / maintainers that a PR is waiting for their review.
+
+   * - .. image:: /_images/pr_label_waiting_on_author.png
+     - Waiting for the author to respond to change requests, feedback, failing
+       tests, etc. Usually this label is used for PRs in board statuses other
+       than “Waiting for Author.”