How to manage Issues
This document details the processes in place for the position of “Issues Manager”, a rotating position within the QA community members.
The Issue Manager job
Your job is to qualify issues submitted to the GitHub project. Good issues help us discover bugs and provide ideas to improve PrestaShop and the native modules. These are the three questions you must ask yourself:
- Is the issue valid? The issue must be a bug report. We only cover the PrestaShop project (Core + native modules). Request for feature should be converted in GitHub Discussions.
- Has all the needed information been provided? The issue must be understandable and contain the required information as provided in the issue template, complemented with any other detail needed for reproduction.
- Can it be reproduced? An issue can’t be fixed if we can’t reproduce it.
Here are some tips:
- Don’t provide free support. Your job isn’t to help the reporter fix their problem, but to determine if the problem is caused by a defect in the software (or in documentation).
- Be pragmatic about your efforts. It’s the reporter’s responsibility to provide the information needed to reproduce the problem in an understandable way. Don’t waste your energy doing guesswork or waiting for a response.
- Don’t be a robot either. Don’t take these guidelines to the letter. If the reporter makes an effort, try to be flexible.
Issue state & labels
GitHub has only two states for issues: open and closed. We use labels to keep track of issue type, intermediate state, severity and resolution.
Bug– a defect in the software
Deprecated - Feature– a new feature, a change in an existing functionality (deprecated since April 2023)*
Task– an issue to track an action that’s not a fix or improve the software like to release a module or network infrastructure changement. It’s a task mainly to be done by the maintainer dev.
Epic– an Epic is a group of issue that are going to
NMI– “Need More Info” - the issue is waiting for its author to provide more details about their request
Needs specs– the issue is waiting for specification, the development should not start until it’s ready.
Ready– the issue has been specified and is ready to be picked up by a dev
WIP– a dev has claimed the issue and is working on it
Deprecated - TBR– “To Be Reproduced” (deprecated since August 2023)*
Fixed– the issue has been resolved
Rejected– the issue has been analyzed and it was decided no to do it (for whatever reason)
Invalid– the issue is incomplete, cannot be reproduced, or its author is unresponsive
In addition to this label, additional labels can be added for informative purposes:
Can't reproduce– the reported bug cannot be reproduced
Duplicate– the issue has already been reported
- Severity (only for bugs), example here
Trivial– cosmetic, low impact bugs
Minor– low severity bugs
Major– high severity bugs
Critical– shop-stopper bugs
Verified– the bug report has been successfully reproduced
Deprecated - Regression– the bug breaks a feature that was working well before (deprecated since August 2023)*
Developer Feature– technical feature, targeting developers
<branch>– where the bug has been reproduced on current branch like
- Solution available – known solution for a bug that hasn’t been fixed/released yet
PR available– a PR fixing the bug is available
Workaround available– a workaround for the bug has been shared
WS(Webservices) … - Which part of the software the feature bug/feature is applied
<Page / Section>- e.g.
ProductWhich page/section the feature bug/feature is applied
<Module name>– Name of the native module the bug / feature belongs to
developlabel, try to specify the branch like
The first thing to do is to deal with the new issues. This can be done by filtering out New issues. Each of these issues must be managed according to the issue processing protocol.
Issues with the NMI label
The second step is to deal with issues labelled
NMI (Need More Info) without
Waiting for author label, which could have been updated by the author or any member of the community. To do this, you have to display the NMI labeled issues without
Waiting for author and sort them by decreasing date of update. NMI issues are issues where crucial information is missing that only the author can provide, usually details on the reproduction steps. If the author or any member of the community has replied and provided the requested details, the issue will proceed according to the issue handling protocol.
Issues to be closed
Finally, the third step consists in tracing the issues that have not been updated for more than 20 days, and closing them. To do this, you have to filter by increasing date and on the
Waiting for authorfilter. Steps :
- Comment with the “Issue without answer” model
- Remove the
- Add the label
- Close the issue
End of the day
Take the time to list the issues reproduced and taken into account during the day. Send an email to [email protected], [email protected], [email protected] AND [email protected] with a brief report, with a list of validated issues (aka taken into account) and duplicated issues and share the same content on Public Slack with project-members.
Hello, Here is the report of the day xx/xx/2020 #Verified - [#18338](https://github.com/PrestaShop/PrestaShop/issues/18338): BO - Module permissions are not updated for restriction groupIssues fermées car doublons #NMI - [#28275](https://github.com/PrestaShop/PrestaShop/issues/28275): Context CurrentLocale not initialised when running a module update #Closed - [#18345](https://github.com/PrestaShop/PrestaShop/issues/18345): Duplicate of [#12556](https://github.com/PrestaShop/PrestaShop/issues/12556) => Installation Error: the % symbol is doubled on the parameters.php file generation Kind regards, xx
The handling of issues follows a detailed process. Here are the different steps, to be followed in order
First and foremost
Check that the report is really an issue!
- Deprecated - if it’s a feature request, redirect to the appropriate template. (since April 2023)
- If it’s a question you’re not obliged to answer it. Remember that the issues section is not a Q&A forum and that your job isn’t to provide free support. Redirect the reporter to a support plan using the “Issue is a support request” response.
- If it’s something that you think should be described in documentation, consider pinging the developers or moving the issue to the docs project.
- If it is a clearly incomprehensible request, close the issue by adding the
Invalidlabel and answer using the “Issue not completed” response.
Issues must be written in English. If that’s not the case:
- Answer using the “Issue not in English” template.
- Set status label to
NMI(Need More Info) +
Waiting for author.
The issue (Bug) must be complete. In particular, all mandatory fields in the template must be completed:
- Describe the bug and add screenshots: full details about the bug. This part represents the “observed behavior” following user manipulations.
- Expected behavior: the “behavior expected” by the user, to be opposed to the observed behavior detailed above. This is the nominal behavior of the application. Pay attention to the specifications.
- Steps to Reproduce: the steps to reproduce the problem. This is the most important part and must be completed in a comprehensive manner.
- PrestaShop version(s) where the bug happened: all affected versions
- PHP version(s) where the bug happened: PHP version
- If your bug is related to a module, specify its name and its version: the module name and its version
In case any information is missing:
- Reply using the “Incomplete Issue” template.
- Set status label to
NMI(Need More Info) with
Waiting for authorlabel.
- Don’t forget to add the necessary labels like : version (
8.1.x, …), Categoy (
FO, …), Pages (
Order, …), …
If it is a
Task, add the necessary labels and place it in Project Kanban:
- If the task is dev oriented, add the
- If the issue seems properly specified, set the status label to
Ready. Otherwise, set it to
- Don’t forget to add these labels like : Categoy (
FO, …), Pages (
Order, …), ….
It is important to avoid creating a duplicate bug. To do this, we must search in GitHub to make sure the issue hasn’t already been created. This step is critical. To do this, use labels to filter as many issues as possible in GitHub. Be careful, remember to look at the closed issues.
If a duplicate is found:
- Answer using the “Duplicate Issue” template.
- Add the
- Close the issue.
Reproducing the issue
We must be able to reproduce the bug in a controlled environment. You can record your attempt, use a screen recorder (like Screencastify, a Chrome extension), download it and then upload it on Github, post it in a comment so that the issue’s author can see the steps you used to reproduce their issue, either on the current branch or on develop branch, depending of what the author declared in his issue.
If the issue cannot be reproduced
We were not able to reproduce the issue like the author described, even with all possible infos provided.
- Answer using the template “Non reproducible issue”.
- Add the label
Waiting for author.
- Wait 20 days, if there is no new information, you can close the issue with the message “unanswered issue”.
If the issue CAN be reproduced
Once we have reproduced the issue with all the details given by the author, we need to check if the bug exists in the next stable PrestaShop version to be released.
The issue is not reproduced in the next stable PrestaShop version
That means the issue has since been corrected. So you have to find the PR that fixes the problem (it can be a migration PR, or a PR that fixes something else and fixes the problem by side effect!). We then answer the author to give him the information about the PR that fixes the problem, and tell him to update his version of PrestaShop. The issue is then closed. Add the label “Fixed” and don’t forget to add the milestone.
The issue is reproduced in the next stable PrestaShop version
Now we can say that the report is indeed a bug: we now add the
Now we have to go back up the chain to find the source of the problem. To do this, test the latest stable version of the previous minor release.
If the issue is reproduced: the bug follows the normal course: go to the next step.
If the issue is not reproduced: It’s a regression! Test all the latest patch versions of the current minor version (e.g. 1760, 1761, 1762…) to find out in which version the issue has been introduced. If motivated, look for the PR in question. Then the issue follows the normal course: go to the next step. In addition, it has to be posted on #dev-core (Public Slack). The Project must then be labeled by selecting the label corresponding to the version in which the regression was detected.
This step is critical cause labelling consists on tagging the issue according to its different characteristics and it helps us find a bug when we’re looking for a
duplicate. The different tags are:
- Type (
- Severity (major, minor, …)
- Deprecated - Regression or not (since August 2023),
Verified(if we reproduce the issue)
- Category (
- Affected page or concerned feature (ex:
- Affected version(s),
- Status (NMI, Needs Specs, Ready…)
- … (non-exhaustive list)
A list of labels and their use is available here.
Connecting an issue to an EPIC
Verifiedlabel), it MUST in most cases be connected to an Epic if it already exists.
To do this, perform a search in the Bug classification board where all Epic are listed. If there is a related EPIC, add the issue to the Epic (by editing the description) and ping the product team.
If no Epic clearly corresponds to the issue (or in case of doubt), just add the bug issue to the 1st column of the kanban called “waiting for classification”. The product team will regularly review the issues in this kanban and create new Epics when needed.
Note that the product team must be able to understand the bug to be able to classify it in an Epic. This means that if the issue is not correctly described nor labelled, or if this is a very tech issue, it MUST NOT be added to the kanban.
Rewriting the issue
Once all the steps have been completed, the content of the issue should be rewritten if it is unclear, or if the author has clarified in the comments. All necessary information should be available in the body of the issue! It may be necessary to rewrite the title if it is too generic (e.g. “Help! BUG!") or if it does not accurately reflect the bug.Pay special attention to the reproduction steps (“how to reproduce”)!
Validating the issue
If the issue is complete and unique, it’s time to validate it! For that, after having correctly labelled it, we use the “Issue validated” model. It is important to ping the team best able to answer the author’s questions: the devs, the product, the support, the qa…
Issue not in English
Hello, Please send your request in English. English is the norm on GitHub. Thank you
Issue for 1.6
Hello, PrestaShop 1.6 has reached end of life and is no longer officially maintained ([see announcement](https://build.prestashop-project.org/news/2019/1.6.1.x-what-s-next/)). Maintenance for this version is now being performed exclusively by volunteers on a very limited scope. You can open an issue on its [dedicated repository](https://github.com/PrestaShop/PrestaShop-1.6/issues), but please keep in mind that only absolutely critical issues may be acknowledged. Thank you
Hello, Despite our efforts, we were not able to reproduce your issue with the provided information. Let's wait up to 20 days if there will be another contributor who encounter the same issue and can provide new informations to help us reproducing the issue. Thank you!
Hello, We are aware of this issue, it is already in our debug backlog. This issue is a duplicate of #Issue_number. To be informed when it's fixed, please subscribe to the issue mentioned above. Thank you
In addition to the message above, add a second comment containing the following sentence:
Duplicate of #Issue_number
This message is special and will trigger a GitHub tag to mark the issue as “duplicate” and link it to the original issue.
Hello [name], Since we had no news from you for more than 20 days, I'll close this ticket to avoid cluttering up the backlog. Please note that you can always create a new one if further information pops up. Thank you
Hello, I reproduce the issue with PrestaShop version x.x.x, I'll add this to the backlog so it can be fixed. Please be aware that some issues might take a very long time to be resolved. If this one is important to you and you cannot wait for it to be fixed on the project’s own time, we strongly suggest you consider [contacting a professional](https://www.prestashop-project.org/support/) to help you. If you fix the issue on your end, please [contribute it back to the project](https://devdocs.prestashop-project.org/8/contribute/contribute-pull-requests/). Remember that the more people contribute, the better PrestaShop becomes for everyone. Thank you
You can personalize the message according to your needs, for example:
For active contributors, it’s not necessary to add this block:
If this one is important to you [...], the better PrestaShop becomes for everyone.
Instead, you can add this:
We’re waiting for your PR 🚀
Issue not completed
Hello [name], Thank you for submitting this issue. Unfortunately, there is not enough information provided to reproduce it and work on it. **You must follow the template and provide clear and concise steps to reproduce the bug**. Read more about how we expect the issues to be handled [here](https://build.prestashop-project.org/news/2020/how-bug-reports-are-handled/). Feel free to create a new issue if you can provide further information, we will be glad to investigate it. Thank you
Issue is a functional feature request
Hello, Thank you for your suggestion. The Maintainer Team will take it into consideration for future developments. Please be aware that there is no guarantee that this feature will be developed anytime soon. If this is important to you, we strongly suggest you consider [contacting a professional](https://www.prestashop-project.org/support/) to help you create it. If you or anyone else is willing to [contribute this feature](https://devdocs.prestashop-project.org/8/contribute/contribute-pull-requests/) to the PrestaShop Project, the teams will be happy to help by ensuring that it fits well within the project. Please let us know if that is the case! Thank you
For active contributors, it’s not necessary to add this block:
If this one is important to you [...] Please let us know if that is the case!
Instead, you can add this:
We’re waiting for your PR 🚀
Issue is a support request
Hello, We only use GitHub issues to discuss about bugs and new features in the PrestaShop project. If you need support, you can find resources to help you on this page: [Get help with PrestaShop](https://www.prestashop-project.org/support/). Thank you
Issue is too technical to reproduce
Hello, Thanks for reporting this issue! Ping @PrestaShop/committers : Could someone please try to reproduce the issue, it's too technical! Thanks in advance!
Issue about an archived module
Hello, This module has been archived, it’s no longer maintained but you still can fork it if you need it for your shop. Also let us know if you are voluntary to maintain this module. Thanks in advance!
Miscellaneous notes (to be read!)
The “NMI” (Need More Info) tag is used at the beginning of the life of the issue, when there are still questions about the issue (quality, completeness, etc).
“Waiting for Author” is used for conversations with the author and for NMI issues when we answers. The issue-bot will delete the label when the author answer (to help us filtering the issues that needs answers, check the filter).
In case of regression discovery, it is essential to share the regressions on #dev-core (Public Slack) and to put them in the right project (e.g. if the regression is on PS 184.108.40.206, we put it in the project 220.127.116.11 and in the project Maxi Kanban, then the PM will prioritize it).
Don’t hesitate to ping the devs/product/QA on issues where their expertise could help, and to add the corresponding label (“Waiting for PM”, “Waiting for Dev”, etc).
- If you ping someone, ask a direct question! Don’t waste their time by making them read the whole thread and guess why did you ping them.
- If the issue is too technical to reproduce, add the “TBR” and “Waiting for Dev” labels. You should also ping @PrestaShop/committers on the issue.
If you don’t know if the issue
Minor, please post it in #quality-assurance and ping QA lead (@Robin Fischer), so they can settle the severity.