|
| 1 | +--- |
| 2 | +group: contributor-guide |
| 3 | +title: Github Issue Processing Workflow |
| 4 | +--- |
| 5 | + |
| 6 | +The Github issue workflow ensures that issues are clear, well written, and thoroughly vetted. Following these procedures allows valid issues to get the attention they deserve. |
| 7 | + |
| 8 | +Magento issues that are reported on the public [GitHub](https://github.com/magento/magento2/issues) must pass through a series of gates, or stages of quality assessment, to ensure that their quality meets our standards. There are three gates, and an issue must pass through all three of these assessments before we will transfer it to either Magento core developers or community developers. |
| 9 | +The purpose of these gates is to identify core technical issues common to all reported tickets, and to show the progress on each reported issue. |
| 10 | + |
| 11 | +## Issue Gates |
| 12 | + |
| 13 | +Issue gates are a series of steps that are run to make sure the issue has all the information needed to reproduce the bug. This includes system configurations, required Magento configurations, reproduction steps and any other required information. |
| 14 | + |
| 15 | +* Gate 1: Automatic verification - an automated process that confirms that the issue contains all the required items. |
| 16 | +* Gate 2: Manual verification - Someone manually confirms that all necessary information has been provided: steps to reproduce, sys configs. |
| 17 | +* Gate 3: Reproduce the bug - Someone sets up a Magento environment and tries to reproduce the bug. The issue is then confirmed or closed. |
| 18 | + |
| 19 | +### Gate 1 - Automatic verification |
| 20 | + |
| 21 | +Gate 1 automatically verifies that the reported issue follows the [Issue Reporting Guidelines](https://github.com/magento/magento2/wiki/Issue-reporting-guidelines). |
| 22 | +The reported issue must contain **all** the following keywords in the description section: |
| 23 | + |
| 24 | +* _Preconditions_ |
| 25 | +* _Steps to Reproduce_ |
| 26 | +* _Actual Result_ |
| 27 | +* _Expected Result_ |
| 28 | + |
| 29 | +**Results**: |
| 30 | + |
| 31 | +* Label `Issue: Format is valid` is added if the issue passes the automatic format verification |
| 32 | +* Label `Issue: Format is not valid` is added if the issue fails the automatic format verification |
| 33 | +* Maintainer can fix the issue description and add missing information. Label `Progress: needs update` will be added. Reporter has 14 days to update the issue description; otherwise, we will close the issue. |
| 34 | +* Maintainer can update the issue description format if sufficient information is provided. |
| 35 | + |
| 36 | +### Gate 2 - Manual verification |
| 37 | + |
| 38 | +Gate 2 verifies a submitted issue is ready for development. |
| 39 | +By the end of the process, it has been vetted for development including all labels for components, affected versions, and so on, reproduction steps are correct, and all the format passes automated review. |
| 40 | + |
| 41 | +**Supporting the Process**: Working on an issue report as a reporter, maintainer, or developer is always a commitment. It is beneficial for every participating party to monitor activity and comments on the ticket during it's lifetime, and provide necessary information or insights. |
| 42 | + |
| 43 | +#### Preparation |
| 44 | + |
| 45 | +Steps for reviewing the issue, verifying reproduction steps, and assigning a Maintainer to work it. |
| 46 | + |
| 47 | +1. Maintainer picks a ticket from the GitHub tracker which is not yet processed. The recommended tool is [Community Backlog](https://github.com/magento/magento2/projects/20) Dashboard. |
| 48 | +2. A maintainer reviews the list from "Ready for QA" column and selects an issue to begin processing. |
| 49 | +3. After selecting the ticket, the maintainer checks the description and reproduction steps. |
| 50 | +4. When the maintainer is ready to start processing the issue, the maintainer should assign the ticket to himself. This indicates someone is actively working on the issue. |
| 51 | + |
| 52 | +#### Validation |
| 53 | + |
| 54 | +Steps for validating the issue format and all information provided checks out: described steps to reproduce are valid, expected behavior is valid, configuration described in preconditions is valid. |
| 55 | + |
| 56 | +1. When the issue is entered, the Automated Contributor Assistant automatically checks the format and assigns one of the following labels after review: `Issue: Format is valid` or `Issue: Format is not valid`. |
| 57 | +2. If the format is not valid (receives `Issue: Format is not valid`), the maintainer should read the report carefully and edit the issue to better match one of the required [templates](https://github.com/magento/magento2/tree/2.4-develop/.github/ISSUE_TEMPLATE). The maintainer edits the report content to comply with requirements. |
| 58 | +3. After saving any changes, the Automated Contributor Assistant runs again and updates the format label (usually less than one minute). |
| 59 | +4. A maintainer can select the issue and review all information, reproduction steps, etc. If the information is incomplete, the maintainer requests more information from the reporter and applies the label `Progress: needs update`. All work pauses on this ticket until the reporter provides more information. |
| 60 | +5. If the ticket has enough information, the maintainer analyzes the problem described in the ticket: described steps to reproduce are valid, expected behavior is valid, configuration described in preconditions is valid. |
| 61 | +6. Is it validated? |
| 62 | + |
| 63 | + * If all provided information is clear and sufficient, it is validated. The maintainer applies the `Issue: Clear description` label to indicate that ticket is ready for manual testing. |
| 64 | + * If it is not validated, the maintainer adds the label `Progress: needs update` and requests more information from the reporter. |
| 65 | + |
| 66 | +### Gate 3: Reproduce the issue |
| 67 | + |
| 68 | +In gate 3, the issue is reproduced in the code. |
| 69 | +Be advised, we only accept pull requests for `2.4-develop`. |
| 70 | + |
| 71 | +1. Maintainer checks if the issue exists on the `2.4-develop` branch with a clean installation, configured by described preconditions, following the exact reproduction steps. |
| 72 | + |
| 73 | + * If the described behavior **was** reproduced, the maintainer should apply the `Reproduced on 2.4` label to the ticket, indicating that issue was reproduced and specific version. |
| 74 | + * If the issue **was not** reproducible with `2.4-develop`, the maintainer should close the issue and **stop verification process here!** |
| 75 | + * |
| 76 | +2. If steps required to reproduce were different from the initially described reproduction steps, update the ticket description with the actual information. |
| 77 | +3. Based on the verification flow, add at least one or more `Component: xxx` labels to the issue. See [Magento Components Assignment](https://github.com/magento/magento2/wiki/Magento-Components-Assignment) for a list. Use your best judgment to determine the components affected. |
| 78 | + |
| 79 | +## Finalization |
| 80 | + |
| 81 | +Steps for final review of issue for contributors/developers to work the issue. |
| 82 | + |
| 83 | +1. Please make sure that all required conditions are met: |
| 84 | + * [ ] Issue format is considered valid by automatic system. |
| 85 | + * [ ] Issue is reproducible at least with one of the supported versions and labeled appropriately. |
| 86 | + * [ ] At least one `Component` label(s) applied to the ticket. |
| 87 | +2. Add the label `Issue: Confirmed` to the ticket. |
| 88 | +3. Wait for the response from the Automated Contributor Assistant, which normally takes 30-60 seconds. |
| 89 | +4. If all required information was provided Automated Contributor Assistant will apply label `Issue: Ready for work` and comment with reference ticket numbers. Otherwise, label `Issue: Confirmed` will be removed and information on what's missing in the report will be provided to the maintainer. |
| 90 | +5. Unassign the ticket from yourself so that developers can claim the issue and start development. |
| 91 | + |
| 92 | +If the issue was reproduced on `Gate 3`, we’ll create an internal `MAGETWO` ticket to track the progress of the issue. |
| 93 | + |
| 94 | +Once an issue has been acknowledged, either Magento core developers or Magento community developers may fix it. We encourage everyone to join the Magento Community Contribution Team and submit Pull Request with the bug fix to [magento/magento2](https://github.com/magento/magento2/pulls) repository. |
| 95 | + |
| 96 | +## Tips and tricks |
| 97 | + |
| 98 | +* If you need a proper testing environment, a verification instance with limited capabilities may be [requested](https://devdocs.magento.com/guides/v2.4/contributor-guide/contributing.html#contributor-assist) from the Automated Contributor Assistant. |
| 99 | +* In most of the cases, we don't recommend verifying issues on older patch versions, even if it was supplied in the preconditions. Generally, fixes can only be provided with the next patch version, and not with any of the older patches. |
| 100 | +* Always follow the [Code of Conduct](https://github.com/magento/magento2/blob/2.4-develop/.github/CODE_OF_CONDUCT.md) in issue comments and discussions. |
| 101 | + |
| 102 | +## Glossary |
| 103 | + |
| 104 | +The following terms help define the process: |
| 105 | + |
| 106 | +* `Reporter` – User who filed initial issue report. |
| 107 | +* `Maintainer` – User a member of Community Maintainers Team who is and working on the issue report to update and confirm report in accordance with all requirements. |
| 108 | +* `Automated Contributor Assistant` – Non-human user that performs automatic checks and provides assistance to human users. |
| 109 | +* `Label` – GitHub label applied to the ticket. |
| 110 | + |
| 111 | +Label descriptions: |
| 112 | + |
| 113 | +* `Issue: Format is valid` – label assigned when the issue report content has all required [fields](https://github.com/magento/magento2/tree/2.4-develop/.github/ISSUE_TEMPLATE). This label is controlled by Automated Contributor Assistant. |
| 114 | +* `Issue: Format is not valid` – Label assigned when the issue report content does not match the [format](https://github.com/magento/magento2/tree/2.4-develop/.github/ISSUE_TEMPLATE) or content required for issues. This label is controlled by Automated Contributor Assistant. |
| 115 | +* `Issue: Clear Description` – Label assigned when human proof-reads the issue report and confirms that it is meaningful and may be sufficient to reproduce the issue. |
| 116 | +* `Issue: Confirmed` – Label assigned when the Maintainer reproduced the issue with at least one of active Magento release lines. |
| 117 | +* `Issue: Ready for Work` – Label assigned by the Automated Contributor Assistant, when ticket was added to Magento's internal issue tracker. |
| 118 | +* `Issue: Cannot reproduce` – Label assigned when the described issue is not reproducible by the described scenario or reproduction steps. |
| 119 | +* `non-issue` – Label assigned when the described behavior in the report is correct, expected behavior and not an issue. <!-- was Issue: Not a bug --> |
| 120 | +* `Component: xxx` – Multitude of labels indicating Magento components that may be the origin of the issue. There is a specific label for each major component. For edge cases, `Component: Other` and `Component: Multiple` may be used. See [Magento Components Assignment](https://github.com/magento/magento2/wiki/Magento-Components-Assignment) for a list. |
| 121 | +* `Reproduced on 2.x` - Label indicating the release line where the Maintainer can reproduce the issue. |
| 122 | +* `Progress: needs update` – Label indicating that the issue is pending a response from the reporter. |
| 123 | + |
| 124 | +For additional labels, see the [Contributor's Guide](https://devdocs.magento.com/guides/v2.4/contributor-guide/contributing.html#labels). |
| 125 | + |
| 126 | +## Questions and Discussion |
| 127 | + |
| 128 | +If you have any questions, feedback, or proposals for this workflow, please join the [Community Engineering Slack Workspace](https://opensource.magento.com/slack). We have a [#backlog-maintainers](https://magentocommeng.slack.com/messages/CCV2S9P7S) channel specifically for these discussions. |
0 commit comments