In order to make the process of bug reporting, fixing and testing more efficient, we have prepared the following checklist to help you understand the process better. We know it could be a lot of work to file an effective bug report, but a good report can save hours of developers’ time, and make the bug much more likely to get fixed sooner.
1. Register as a Contributor
If you haven’t done so, please register as a contributor and set your member status to a Contributor.
2. Is It Really a Bug?
If you came across something that you think is a bug – please make sure it is a real bug and not just a problem with your customized code! Also, please make sure it is not how the system is supposed to work. Maybe you are just looking at something differently?
3. Check Documentation and Ask Others to Make Sure
If In-Portal does not behave the way you expect, the first thing to do is to check the Documentation (to make sure it doesn’t work the way it is supposed) and In-Portal Bugs Group (to make sure it is not something the Community is already working on). You can always use your judgment to determine to the best of your abilities whether it is a bug. If you're not sure, just go ahead and ask about in the In-Portal Bugs Group or on In-Portal Forum (Bugs category) to check if it is indeed a problem and if the bug has been reported already.
4. Search the Bug Tracker
Before reporting the bug, please make sure to check and search the In-Portal Issue Tracker (http://jira.in-portal.org/) to see if anyone has already reported this bug. If you do find the bug has been reported already, you are more than welcome to review the existing report and add your comments if you feel they are going to help with reproducing or fixing the bug.
5. Determine the Reproduction Recipe
Once you've established that it's a bug, and that the Community doesn’t know about it already, the most important thing you can do is to come up with a simple reproduction recipe (a sequence of steps or instructions one can follow to reproduce the bug). The more specific the reproduction recipe is, the more likely a developer will be able to reproduce the bug and fix it.
When you write the reproduction recipe, please don't just limit it by a description of what you think may have caused the bug. Please make sure to provide a step-by-step transcript of the exact sequence of actions/steps you performed and their result. If you can’t recreate the bug using your own reproduction recipe, chances are others won’t be either.
It does help to include the names of the files involved (URLs of the pages where the bug happened), screenshots, exact error messages or anything else that you think might be relevant. Also, keep in mind that the bug may be conditional on certain events or circumstances (for example, a certain combination of factors) in which case please make sure to describe what those are.
6. Write down the Environment
In addition to the Reproduction Recipe, you will also need a complete description of the environment in which you are able to reproduce the bug:
- Your Server’s OS, Web-Server, Database Server and PHP versions (i.e. Linux CentOS or Windows 2003 Server, Apache 1.3, MySQL 5.0.55, PHP 5.2.6)
- Your Computer’s OS and Browsers version (i.e. Windows Vista, FireFox 3.5.)
- The release and/or revision of In-Portal or Modules (i.e. 5.0.2, 5.1.0)
- Anything else that could possibly be relevant (other software installed on the server, non-standard configuration settings, etc.)
If you are absolutely sure it is a Server-side bug, you may only include server environment information (and client information for client-side bugs). However, if you are not sure, it is better to include both.
7. Quick Check before Reporting
- Are you running the most recent version of In-Portal (or modules)?
- Are you sure it hasn’t been fixed already? Check to see if there is a patch available (you should test your reproduction recipe against the patches in the most recent In-Portal Development tree: http://fisheye.in-portal.org/)
- We depend on the In-Portal Bugs Group (http://community.in-portal.org/display/BUG/) for quality control of all bug reports. Without filtering by the Bug Team, the tracker would be full of duplicate issues, non-issues, and irreproducible issues. Please help us keep the bug tracker clean, by always finding a bug-buddy (someone who can recreate the same bug) before you file a report!
8. Submitting the Bug Report
Now you're ready to submit a bug report:
Go to http://jira.in-portal.org/ and click on "Create" button. Please make sure to include the following information:
- Component/s – specify the category the bug falls into; try to classify the bug as much as you can (i.e. Front End, Administrative Console, Other, if not sure)
- Affects Version/s – version of In-Portal or module (i.e. 5.0.1, 5.0.2, etc.)
- Summary – clear, short description of what the bug is
- Description – specify how you expected In-Portal to behave, and contrast that with how it actually behaved. While the bug may seem obvious to you, it may not be so obvious to someone else, so it's best to avoid a guessing game. Follow that with the environment description, and the reproduction recipe. If you also want to include speculation as to the cause, and even a patch to fix the bug, that's great – submit it through Phabricator!
- Reproduction Recipe – this is what you have prepared in the “Determine the Reproduction Recipe” step above.
- Environment – this is what you have prepared in the “Write down the Environment” step above along with additional Information (screenshots, etc.)
Follow the Progress
Congratulations! You have just submitted a bug report! You may now follow its progress by subscribing to updates in the Issue Tracker or the Bugs Team.