Bug Reporting Guidelines
These guidelines are brought to you by Diego Ruiz. If you have questions or improvement suggestions, feel free to edit this page.
This is part of a list of all possible contributions, you can check those in Contributing to iDempiere.
Did you find a bug in iDempiere
- Do not open up a JIRA ticket if the bug is a security vulnerability in iDempiere, and instead refer to our How to report a vulnerability page.
- Ensure the bug was not already reported by searching on JIRA under Issues, in case you find the bug already reported check if you can add any useful information to the bug report.
- If you're unable to find an open issue addressing the problem, open a new one. Be sure to include a title and clear description, as much relevant information as possible, and a code sample or a executable test case demonstrating the expected behaviour that is not occurring, it is a good idea if you can reproduce the bug in one of the test servers before you create a ticket.
Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
Before Submitting A Bug Report
- Check if you can reproduce the problem in the latest version of iDempiere.
- Check the FAQs on the forum' for a list of common questions and problems.
How Do I Submit A (Good) Bug Report?
Bugs are tracked as JIRA issues.
Explain the problem and include additional details to help maintainers reproduce the problem:
- Use a clear and descriptive title for the issue to identify the problem.
- Describe the exact steps which reproduce the problem in as many details as possible.
- Provide specific examples to demonstrate the steps. If possible reproduce the problem with Garden data.
- Describe the behaviour you observed after following the steps and point out what exactly is the problem with that behaviour.
- Explain which behaviour you expected to see instead and why.
- Include screenshots and videos - if possible, which show you following the described steps and clearly demonstrate the problem.
- If you're reporting that iDempiere crashed, include a crash report with a stack trace from the log files.
- If the problem is related to performance or memory, include valid numbers.
- If the problem wasn't triggered by a specific action, describe what you were doing before the problem happened and share more information using the guidelines below.
Provide more context by answering these questions:
- Can you reproduce the problem in the test sites?
- Did the problem start happening recently (e.g. after updating to a new version of iDempiere) or was this always a problem?
- If the problem started happening recently, can you reproduce the problem in an older version of iDempiere? What's the most recent version in which the problem doesn't happen?
- Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.
Bug report components
These are the ideal components that a bug report should contain. If your bug is well-reported and clearly defined, it is most likely that the community will try to solve it and work on it.
- Be specific -> i.e. I opened the window XYZ and created a new record filling the fields with the values Name=ABC, Code=XYZ ...
- Be verbose -> more is better than less when providing information for a developer to reproduce your problem
- Be careful of pronouns
- Read what you wrote
- Read this guide
1. Summary (Bug Title)
The short summary of a bug report is the most accessible way of figuring out what the reported issue is. This is the first impression and it usually influences the overall quality of the bug report.
Be pithy, be precise, and be concise (in the subject, but be verbose in the explanation). A developer should be able to read the summary and say, "Oh, that's what the bug is about." A bad summary is "iDempiere isn't working!" Remember, people searching for bugs will often search the summary. Make a good impression: the summary should tell the developer whether or not to look into the bug.
The short summary must be short and must describe the issue in a few keywords.
Examples: Not good enough: 'Incorrect price is shown on order line' This example shows an incomplete description of the issue. Why are those prices incorrect? What actions have you performed before seeing they're displayed there? Good: 'Prices from the price list are still displayed after updating them manually'
2. Actual results in the description
The Actual Results should be written in the description, they represent the behaviour encountered in the app when/after performing certain actions.
The actual results can be the same as the summary if the issue doesn’t require lots of explanations.
Examples: Not good enough: 'The windows in Favourites are still displayed' This Actual results example isn’t good enough because it doesn’t describe the actions performed before encountering the issue. You should answer the question: Why is it an issue that the windows are still displayed? -> Because you previously removed them. You must include the action taken before encountering the issue.
Good: 'After removing a window from the Favourite section, the product is still displayed in the Favourite section.
We advise being as specific as possible in filling the required fields.
3. Expected results in the description
The Actual Results should be written in the description. If you're clicking on a menu item, the expected behaviour is for the corresponding window to be opened.
The Expected results description needs to describe the actions taken before encountering the behaviour, not only the behaviour itself. An Expected Results field that only points out that 'X thing shouldn’t happen' is Not good enough.
Examples: Not good enough: 'The windows in Favourites not displayed' This Expected Results example is not good enough because it doesn’t provide any details as to what is expected to happen. You should also answer the question: 'Why shouldn't the window be displayed anymore?'
Good: 'The windows from Favourites shouldn’t be displayed after removing them.'
4. Steps to reproduce in the description
The steps to reproduce are a key component of the bug report. These instruct the maintainers and community members as to how they should reproduce the issue. It's a lot easier for community to verify the problem if is reproducible in GardenWorld.
If the steps to reproduce are not clear enough, the developers will not be able to reproduce the issue and it will be rejected.
- The steps to reproduce need to provide full visibility on the actions the tester has taken up to the encountered issue.
- The steps to reproduce need to have only 1 action per step.
- The steps to reproduce need to end with a step similar to the Short summary, so that the issue is clear.
Examples:
Not good enough: 1. Open iDempiere and log in 2. Observe
Good: 1. Open iDempiere 2. Login 3. Observe the dashboard panel is shown blank instead of showing the configured dashboards
5. Attachments
It’s crucial for you to provide proof for the bugs you report in JIRA. It is better if you attach to the bug reports, screenshots, videos, log reports that help the maintainers see what happened and what was the issue and how you got there.
6. Bug Template
iDempiere Version : <Copy from: About> Operating System (OS and version): Database (engine and version): Java version: Steps to reproduce 1. 2. 3. Expected results: Actual results? Please provide any additional information below. Attach a screenshot if possible.