diff --git a/source/_images/devguide_branch_conflicts.png b/source/_images/devguide_branch_conflicts.png new file mode 100644 index 000000000..9b24cb772 Binary files /dev/null and b/source/_images/devguide_branch_conflicts.png differ diff --git a/source/_images/devguide_failed_cla_check.png b/source/_images/devguide_failed_cla_check.png new file mode 100644 index 000000000..f3c633b5a Binary files /dev/null and b/source/_images/devguide_failed_cla_check.png differ diff --git a/source/_images/devguide_out_of_date_branch.png b/source/_images/devguide_out_of_date_branch.png new file mode 100644 index 000000000..2cc8bbbfb Binary files /dev/null and b/source/_images/devguide_out_of_date_branch.png differ diff --git a/source/_images/devguide_passing_checks.png b/source/_images/devguide_passing_checks.png new file mode 100644 index 000000000..03901a6e9 Binary files /dev/null and b/source/_images/devguide_passing_checks.png differ diff --git a/source/_images/devguide_pr_status.png b/source/_images/devguide_pr_status.png new file mode 100644 index 000000000..5bba5a151 Binary files /dev/null and b/source/_images/devguide_pr_status.png differ diff --git a/source/_images/devguide_workflow_approval.png b/source/_images/devguide_workflow_approval.png new file mode 100644 index 000000000..e54463b0b Binary files /dev/null and b/source/_images/devguide_workflow_approval.png differ diff --git a/source/_images/pr_label_backport.png b/source/_images/pr_label_backport.png new file mode 100644 index 000000000..2fb81749d Binary files /dev/null and b/source/_images/pr_label_backport.png differ diff --git a/source/_images/pr_label_blocked_by_other_work.png b/source/_images/pr_label_blocked_by_other_work.png new file mode 100644 index 000000000..7fc65e524 Binary files /dev/null and b/source/_images/pr_label_blocked_by_other_work.png differ diff --git a/source/_images/pr_label_changes_requested.png b/source/_images/pr_label_changes_requested.png new file mode 100644 index 000000000..0f8da2294 Binary files /dev/null and b/source/_images/pr_label_changes_requested.png differ diff --git a/source/_images/pr_label_closed-inactivity.png b/source/_images/pr_label_closed-inactivity.png new file mode 100644 index 000000000..95885ed01 Binary files /dev/null and b/source/_images/pr_label_closed-inactivity.png differ diff --git a/source/_images/pr_label_core_contributor.png b/source/_images/pr_label_core_contributor.png new file mode 100644 index 000000000..2eaefa0c4 Binary files /dev/null and b/source/_images/pr_label_core_contributor.png differ diff --git a/source/_images/pr_label_duplicate.png b/source/_images/pr_label_duplicate.png new file mode 100644 index 000000000..346231310 Binary files /dev/null and b/source/_images/pr_label_duplicate.png differ diff --git a/source/_images/pr_label_inactive.png b/source/_images/pr_label_inactive.png new file mode 100644 index 000000000..23fd3afbc Binary files /dev/null and b/source/_images/pr_label_inactive.png differ diff --git a/source/_images/pr_label_needs_maintainer_attention.png b/source/_images/pr_label_needs_maintainer_attention.png new file mode 100644 index 000000000..df9e2a02f Binary files /dev/null and b/source/_images/pr_label_needs_maintainer_attention.png differ diff --git a/source/_images/pr_label_needs_test_run.png b/source/_images/pr_label_needs_test_run.png new file mode 100644 index 000000000..b74ce6da9 Binary files /dev/null and b/source/_images/pr_label_needs_test_run.png differ diff --git a/source/_images/pr_label_open-source-contribution.png b/source/_images/pr_label_open-source-contribution.png new file mode 100644 index 000000000..1ada49058 Binary files /dev/null and b/source/_images/pr_label_open-source-contribution.png differ diff --git a/source/_images/pr_label_product_review.png b/source/_images/pr_label_product_review.png new file mode 100644 index 000000000..555ea953a Binary files /dev/null and b/source/_images/pr_label_product_review.png differ diff --git a/source/_images/pr_label_waiting_for_eng_review.png b/source/_images/pr_label_waiting_for_eng_review.png new file mode 100644 index 000000000..61cd8c3a1 Binary files /dev/null and b/source/_images/pr_label_waiting_for_eng_review.png differ diff --git a/source/_images/pr_label_waiting_on_author.png b/source/_images/pr_label_waiting_on_author.png new file mode 100644 index 000000000..d76d09218 Binary files /dev/null and b/source/_images/pr_label_waiting_on_author.png differ diff --git a/source/developers/references/developer_guide/links.rst b/source/developers/references/developer_guide/links.rst index 58f63c816..4e5f5c54e 100644 --- a/source/developers/references/developer_guide/links.rst +++ b/source/developers/references/developer_guide/links.rst @@ -286,6 +286,7 @@ .. _Accessibility Guidelines: http://edx.readthedocs.io/projects/edx-developer-guide/en/latest/accessibility.html .. _Analytics Guidelines: http://edx.readthedocs.io/projects/edx-developer-guide/en/latest/analytics.html .. _Eventing Design and Review Process: https://openedx.atlassian.net/wiki/display/AN/Eventing+Design+and+Review+Process +.. _Product Review Process: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3875962884/DRAFT+How+to+submit+an+open+source+contribution+for+Product+Review .. _Durham University Alt Text Checker: https://www.dur.ac.uk/cis/web/accessibility/tools/alttext/ diff --git a/source/developers/references/developer_guide/process/FAQ-about-pull-requests.rst b/source/developers/references/developer_guide/process/FAQ-about-pull-requests.rst new file mode 100644 index 000000000..83d6a576c --- /dev/null +++ b/source/developers/references/developer_guide/process/FAQ-about-pull-requests.rst @@ -0,0 +1,179 @@ +###################################################### +Overview of Review Process for Community Contributions +###################################################### + +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 + +======================================= +Community Contribution Project Managers +======================================= + +The main goal of the `Community Contribution Project Managers`_ is to triage all +pull requests that come in from contributors across the community, and help +those PRs get through to being merged. During the triage and review process, the +Community PMs are responsible for: + +* Welcoming new contributors to the community + +* Triaging community pull requests in a timely manner + +* For new contributors, ensuring they submit a CLA form (if contributing as an + individual), or get added to their organization's entity agreement (if + contributing on behalf of their organization) + +* Ensuring the correct amount of detail is provided for the requested change(s) + (e.g. if there is not context or description for your contribution, we'll ask + you to provide one) + +* Making sure checks are able to run on the pull request + +* Routing pull requests to the appropriate reviewers / `maintainers`_, and + making sure they're addressed in a timely manner + +* Connecting contributors with the appropriate people if troubleshooting is + needed, or if there are technical questions + +* Helping to get the pull request merged once everything is approved + +At a high level, the pull request process is as follows: + +#. Initial triage on a new pull request is done by the Community PMs within a few days + + #. Note: some pull requests require review by our Product team. Please see + :doc:`contributor` for requirements needed for the Product team to + properly review your contribution. Ideally, this would be done before code + is written. + +#. If checks need to be enabled, or a CLA form needs to be submitted, the + Community PMs will help get checks running and help with any questions + regarding the CLA + + .. image:: /_images/devguide_workflow_approval.png + + .. image:: /_images/devguide_failed_cla_check.png + +#. If there are checks failing on your pull request, you'll need to look into + what's causing the issue. The Community PM can direct you to someone to help + if needed. + + #. Note: please see :doc:`../../running_pr_tests` that outlines common issues + that pop up while running tests + +#. Once everything is up and running, the Community PMs are available to help + with any questions that come up while product and/or engineering review is + in-progress + +#. If the pull request review process takes a bit longer than expected, you may + notice the following alerts pop up, and the Community Project Managers might + ask you to take some action: + + #. **“This branch is out-of-date with the base branch”** which means you'll + need to rebase your changes. + + .. image:: /_images/devguide_out_of_date_branch.png + + #. **“This branch has conflicts that must be resolved”** which means someone + has changed information in the same file on the target branch of the PR + (which is usually the master). You will need to reconcile those changes + with your own. + + .. image:: /_images/devguide_branch_conflicts.png + +#. When all checks are green, tests are passing, there are no conflicts, and the + work is ready for engineering review, the Community PMs will assign the + appropriate reviewer / maintainer to take a look + + .. image:: /_images/devguide_passing_checks.png + +#. During review, you may receive feedback or change requests that require + action on your part. + +#. Once all feedback and changes have been incorporated, the pull request will + be able to be merged by the reviewer / maintainer. + +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 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 +Community PM checked in on it. To do this, find the "Projects" section, and +click on the "⌄" caret in the top right corner next to "Contributions" to see a +display like this: + +.. image:: /_images/devguide_pr_status.png + +============================ +FAQs about your Pull Request +============================ + +**My pull request has been waiting for review for a few weeks, is something +wrong?** + +No! We receive hundreds of pull requests from the community (which is awesome!), +but that means sometimes the process to get PRs through the review process and +merged might take a bit of time due to things like: + +* The reviewing team is at capacity and needs to review the pull request during a later sprint +* Related work or dependencies may be blocking a PR's ability to be merged + +The Community PMs will do our best to make sure all updates related to delays +are communicated within the PR. Additionally, if the reviewing team needs +additional information or context for your contribution, they will ask within +the PR. + +**There haven't been any updates in my PR in a few weeks. How do you handle +stalled PRs?** + +The Community Project Managers proactively stay on top of pull requests, and +will ping reviewers for updates, actions, etc. when things seem stalled. If you +have any questions, you can tag the assigned Community PM for help / updates in +the PR at any time. + +**I submitted a PR a while ago, something came up, and I am not able to work on +it for the foreseeable future. What happens now?** + +If a PR is stalled on the author's side, the Community PMs will ping the author +a few times before labeling the PR as “inactive” after a month or so. + +* If you want to pursue the PR, but don't have capacity at the moment, please + let us know directly in the PR if possible. At that point we can leave it as a + draft, or we can close it if needed, and can reopen it at a later time if + you're able to pursue it. +* If an author is unresponsive for a month or more, or hasn't had capacity to + come back to check on the PR, the Community PMs may need to close the PR due + to inactivity (though, again, it can be reopened at a later time if needed). + +**My PR was labeled as “blocked” - what does that mean?** + +Occasionally, a pull request may get blocked by other on-going or related work. +The Community PMs will stay on top of it to make sure it gets unblocked as soon +as possible, but note that it may take a bit depending on what's blocking it. +Updates from the Community PMs and reviewing team should be made in the PR so +you have updated information. + +**My PR was closed and not merged - why?** + +There may be times where a pull request is closed (instead of merged) by an +owning team because the update may no longer be needed, it's duplicative of +other work, or other reasons. The reason for closing the pull request should be +made clear to you in the PR, and if it's not, the Community PM assigned to your +pull request can help you get that information. + + + +.. _Community Contribution Project Managers: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3548807177/Community+Contributions+Project+Manager +.. _maintainers: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3426844690/Maintainership+Pilot diff --git a/source/developers/references/developer_guide/process/contributor.rst b/source/developers/references/developer_guide/process/contributor.rst index faef1a356..9ac7768ed 100644 --- a/source/developers/references/developer_guide/process/contributor.rst +++ b/source/developers/references/developer_guide/process/contributor.rst @@ -1,47 +1,75 @@ -.. _Contributor: - ************ Contributing ************ +Contributing your custom code to the Open edX project is a two-step process: +review of your idea by the product team (the Product Review Process), +followed by a review of your code by the project's core committers. +We describe this process on the `Product Review Process`_ wiki page. + +Note:: + + By and large, bug fixes do not require the Product Review Process. + However, if your bug fix will change user facing behavior, you should + check with the Product Working Group on the best way to land your fix + before beginning to write code. + +---------------------------------------- +Product Review Process & Product Roadmap +---------------------------------------- + +New features added to the Open edX project go through a `Product Review +Process`_, lead by the `Open edX Product Working Group`_. If you're interested +in adding new features, we ask that you undergo the product review process +_before_ you begin coding your feature. This allows the project to get +alignment on new features and help guide you to implement the feature in +a way that works with the overall platform. Additionally, there might well +be someone else already working on the same change you want to make, +and it's much better to collaborate than to submit incompatible pull requests. ------------------- -Finding Work To Do ------------------- +If you open up your feature request with a solid description, the product owners +will be able to quickly understand your change and prioritize it for +review. However, they may have some questions about your intention, need, +and/or approach that they will ask about. -TODO: Add Content Here (how to use Feature Requests & Product Roadmap) +To read more about the product review process and how to submit your idea, +please visit the `Product Review Process`_ wiki page. -Before you make a pull request, it's a good idea to reach out to the -Open edX community to discuss your ideas. There -might well be someone else already working on the same change you want to make, -and it's much better to collaborate than to submit incompatible pull requests. -The `Community Discussions`_ page on the openedx.org website lists different -ways you can ask, and answer, questions. The earlier you start the -conversation, the easier it will be to make sure that everyone's on the right -track. +Features that the project wants, as well as ones being currently worked on +by community members, are represented on the `Product Roadmap`_. This +kanban-style board represents units of work on individual cards. Check +out the tickets on the far left for help reading the board. The tabs at +the top will allow you to drill into roadmap tickets by platform area. -.. _Community Discussions: https://openedx.org/community/connect/ +If you're interested in contributing to the Open edX project but don't know +what to contribute, check out the roadmap! If you're interested in picking +up or collaborating on a ticket, join the conversation by adding a comment +on the ticket. -It's also sometimes useful to submit a pull request even before the code is -working properly, to make it easier to collect early feedback. To indicate to -others that your pull request is not yet in a functional state, just prefix the -pull request title with "(WIP)" (Work In Progress), or start the pull request -as a draft on GitHub. Please include a link to a WIP pull request in any -discussion threads you start. +---------------------------- +Getting Preliminary Feedback +---------------------------- +It is sometimes useful to submit a pull request even before the code is +working properly, to make it easier to collect early feedback on your +implementation. To indicate to others that your pull request is not yet in a +functional state, just prefix the pull request title with "(WIP)" (Work In +Progress), and start the pull request as a draft on GitHub. ----------------- -Landing The Work ----------------- +Please include a link to your roadmap ticket in the PR description, and add a +link to a WIP pull request in any discussion threads you start. -TODO: Update This Section +----------------- +Landing Your Work +----------------- -Once you're ready to submit your changes in a pull request, check the following +Once you're ready to submit your code changes in a pull request, check the following list of requirements to be sure that your pull request is ready to be reviewed: -#. Prepare a detailed pull request description. When you open - your pull request, put your cover letter into the "Description" field on - GitHub. +#. Prepare a detailed pull request description. Most repositories have a template + to be followed when you open the PR in the GitHub UI. Please fill out that template + with as much detail as possible, including links to any roadmap tickets or + forum discussions as well as screenshots or screencasts. #. The code should be clear and understandable. Comments in code, detailed docstrings, and good variable naming conventions are expected. See the @@ -65,7 +93,7 @@ list of requirements to be sure that your pull request is ready to be reviewed: request, for forensic purposes when trying to diagnose a regression or understand a bug. -#. All code in the pull request must be compatible with Open edX's AGPL +#. All code in the pull request must be compatible with the Open edX project's AGPL license. This means that the author of the pull request must sign a `contributor's agreement`_, and all libraries included or referenced in the pull request must have `compatible licenses`_. @@ -88,19 +116,18 @@ list of requirements to be sure that your pull request is ready to be reviewed: #. For pull requests that make changes to the user interface, please include screenshots of what you changed. GitHub will allow you to upload images - directly from your computer. In the future, the core committers will produce - a style guide that contains more requirements around how pages should appear - and how front-end code should be structured. + directly from your computer. Changes should only use elements from the + `Paragon pattern library`_. #. The pull request should contain some documentation for the feature or bug - fix, either in a README file or in a comment on the pull request. A well- - written description for the pull request may be sufficient. + fix. A well-written description for the pull request is often sufficient. #. The pull request should integrate with existing infrastructure as much as - possible, rather than reinventing the wheel. In a project as large as Open - edX, there are many foundational components that might be hard to find, but - it is important not to duplicate functionality, even if small, that already - exists. + possible, rather than reinventing the wheel. In a project as large as ours, + there are many foundational components that might be hard to find. + It is important not to duplicate functionality, even if small, that already + exists. Posting in the `forums`_ is an easy way to find out if functionality + you're looking for already exists. #. The author of the pull request should be receptive to feedback and constructive criticism. The pull request will not be accepted until all @@ -111,13 +138,17 @@ list of requirements to be sure that your pull request is ready to be reviewed: comment explaining why the contributor has chosen not make any change based on that feedback. +While your pull request is open, you may have questions about how things are +going, or how to check in on the progress of your review. We've prepared a +:doc:`FAQ-about-pull-requests` that should answer most of your questions. + It's also important to realize that you and the core committers may have different ideas of what is important in the codebase. The power and freedom of open source software comes from the fact that you can fork our software and -make any modifications that you like, without permission from us. However, the +make any modifications that you like without permission from us. However, the core contributors are similarly empowered and free to decide what modifications to pull in from other contributors, and what not to pull in. While your code -might work great for you on a small installation, it might not work as well on +might work great for you on your installation, it might not work as well on a large installation, have problems with performance or security, not be compatible with internationalization or accessibility guidelines, and so on. There are many, many reasons why the core committers may decide not to accept @@ -126,18 +157,6 @@ code change. However, if we do reject your pull request, we will explain why we aren't taking it, and try to suggest other ways that you can accomplish the same result in a way that we will accept. -Once A PR is Open ------------------ - -If you open up your pull request with a solid description, the product owners -will be able to quickly understand your change and prioritize it for -review. However, they may have some questions about your intention, need, -and/or approach that they will ask about. A community -manager will ping you on GitHub to clarify these questions if they arise. - -Once the product team has sent your pull request to the engineering teams for -review, all technical discussion regarding your change will occur on GitHub, -inline with your code. Further Information ------------------- @@ -156,3 +175,8 @@ following links: .. _contributor's agreement: http://openedx.org/cla .. _compatible licenses: https://openedx.org/open-edx-licensing .. _OEP-51\: Conventional Commits: https://open-edx-proposals.readthedocs.io/en/latest/best-practices/oep-0051-bp-conventional-commits.html +.. _Paragon pattern library: https://paragon-openedx.netlify.app/ +.. _forums: https://discuss.openedx.org/ +.. _Product Review Process: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3875962884/DRAFT+How+to+submit+an+open+source+contribution+for+Product+Review +.. _Open edX Product Working Group: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3449028609/Product+Working+Group +.. _Product Roadmap: https://github.com/orgs/openedx/projects/4 diff --git a/source/developers/references/developer_guide/process/core-contributors.rst b/source/developers/references/developer_guide/process/core-contributors.rst index 8e1e8cbdb..71fcf2947 100644 --- a/source/developers/references/developer_guide/process/core-contributors.rst +++ b/source/developers/references/developer_guide/process/core-contributors.rst @@ -15,12 +15,12 @@ other community members, and are generally polite and welcoming. Core Contributors that write code gain write access and even maintainership to one or more GitHub repositories in the openedx/ GitHub organization. If you're interested in becoming a Core Contributor, the following resources may be helpful to you. You can -also find us on the `Open edX Slack ` in the #core-contributors +also find us on the `Open edX Slack `_ in the #core-contributors Slack room. ---------- +========= Resources ---------- +========= * `Core Contributor program homepage `_ * `Open edX Proposal 54 `_, which defines the Core Contributor Program diff --git a/source/developers/references/developer_guide/process/index.rst b/source/developers/references/developer_guide/process/index.rst index 31f6a92a3..7255eed59 100644 --- a/source/developers/references/developer_guide/process/index.rst +++ b/source/developers/references/developer_guide/process/index.rst @@ -1,8 +1,8 @@ .. _Contributing to Open edX: -########################### -Contributing to Open edX -########################### +#################################### +Contributing to the Open edX Project +#################################### .. toctree:: :maxdepth: 2 @@ -10,4 +10,6 @@ Contributing to Open edX overview contributor code-considerations + FAQ-about-pull-requests + pull-request-statuses core-contributors diff --git a/source/developers/references/developer_guide/process/overview.rst b/source/developers/references/developer_guide/process/overview.rst index 9ebe19fc3..c86785755 100644 --- a/source/developers/references/developer_guide/process/overview.rst +++ b/source/developers/references/developer_guide/process/overview.rst @@ -20,6 +20,7 @@ and other contributors can expect from each other. The goals are: as much as possible. +------------------ General Guidelines ------------------ @@ -27,16 +28,12 @@ Please follow these guidelines when writing code. Please note that not all of these may be required for your feature; reach out to us if you have any questions or concerns. +* For new features, or any changes affecting user behavior, please follow the + `Product Review Process`_ * `Internationalization Coding Guidelines`_ * `RTL UI Best Practices`_ * `Accessibility Guidelines`_ * `Analytics Guidelines`_ * `Eventing Design and Review Process`_ - -Roles ------ - -TODO - .. include:: ../links.rst diff --git a/source/developers/references/developer_guide/process/pr-process.graffle/data.plist b/source/developers/references/developer_guide/process/pr-process.graffle/data.plist deleted file mode 100644 index 4f408c68d..000000000 Binary files a/source/developers/references/developer_guide/process/pr-process.graffle/data.plist and /dev/null differ diff --git a/source/developers/references/developer_guide/process/pr-process.graffle/image2.png b/source/developers/references/developer_guide/process/pr-process.graffle/image2.png deleted file mode 100644 index 9d65374d4..000000000 Binary files a/source/developers/references/developer_guide/process/pr-process.graffle/image2.png and /dev/null differ diff --git a/source/developers/references/developer_guide/process/pr-process.png b/source/developers/references/developer_guide/process/pr-process.png deleted file mode 100644 index 79e20b473..000000000 Binary files a/source/developers/references/developer_guide/process/pr-process.png and /dev/null differ diff --git a/source/developers/references/developer_guide/process/pull-request-statuses.rst b/source/developers/references/developer_guide/process/pull-request-statuses.rst new file mode 100644 index 000000000..0f5f9d3d7 --- /dev/null +++ b/source/developers/references/developer_guide/process/pull-request-statuses.rst @@ -0,0 +1,129 @@ +========================= +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. + * - **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 ` 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 Project 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”. + + * - .. image:: /_images/pr_label_duplicate.png + - This issue or pull request already exists elsewhere. \ No newline at end of file