Bug Reporting Guidelines
If you have found a defect or you want to request a feature enhancement an issue report is the way to bring the attention to the Openbravo Community.
The Openbravo Issue tracker is the database of defects and feature requests for the Openbravo projects. It helps developers keep track of issues and who is fixing them. Users can join Openbravo effort by making their bug reports clear and specific. The better the issue is reported, the easier it is to identify the cause, and fix it.
The Issue Life Cycle
Before you start working with issues, it is important that you have a good understanding of the issue management process at Openbravo, which is represented in the following diagram using the BPMN notation.
There are four actors involved in this process:
- Reporters: who log issues
- Triage team: who reviews new issues and decides how to handle them by either:
- Acknowledging them as valid;
- Scheduling them for resolution;
- Asking the reporters for more feedback;
- Rejecting them.
- Engineers: who resolve (fix) the issues.
- QA testers: who test that issues are properly fixed.
The progression along this process is tracked using the issue status, which can evolve according to the following status transition diagram.
Openbravo uses two classifications for issues:
Issue Type classifies whether an issue is a:
- Defect: used to report a malfunction where the product does not work as specified.
- Design defect: used to report a problem with current functionality that will require a redesign of a functional flow
- Feature Request: used to request a new feature in the product or a modification in the specified behaviour of an existing one.
- Backport: normally, defects are only fixed in pi, which means that they will be available only in the next release. Backports are replications of defects in a maintenance branch. Never use issue type Backport when reporting an issue.
We are aware that distinguishing among defects, design defects and feature requests often is not an easy task and that there are a number of situations where this is not a clear cut choice: sometimes the intended behaviour is not clear or, worse, the product might work as specified but the specification might not meet the users' requirements. That said, we believe that this is an important distinction as every type should be handled differently. In particular, defects should be resolved at the earliest opportunity while design defects and feature requests require planning, design and therefore need to be explicitly scheduled for a given release. Also, design defects should address any potential void in the functional requirements while feature requests should focus on functionality that does not exist yet or it is not complete.
Projects are the highest level of containers for issues and an issue must belong to one and only one project.
Projects determine who is responsible for resolving the issue and what attributes must be captured during the issue life cycle. Additionally, summary level statistics, road maps and change logs are all maintained at project level.
Openbravo uses the following projects:
- Openbravo POS: for any issue related to Openbravo POS.
- Openbravo ERP: for any issue related to Openbravo ERP platform and functionality.
- Openbravo ERP Quickstart: for any issue related to Openbravo ERP Quickstart version.
- ERP Professional Subscription: for any issue related to Openbravo ERP Professional Subscription solutions (Appliance stack and Ubuntu package).
- ERP Extensions: for issues related to extensions to Openbravo ERP (localization packs and modules) managed by Openbravo.
- Pentaho Integration: for issues related to the integration with Pentaho Business Intelligence (BI) server.
- Localization Pack: Spain: for issues related to the Spanish Localization Pack.
- Accounting Alerts
- CIF and NIF validator
- Invoice Register Book
- Libro de Facturas - es_ES
- Spain AEAT Modelo 347
- Spain AEAT Modelo 347 - es_ES
- Spain AEAT Modelo 349
- Spanish Bank Account Validation
- Spain Chart Of Accounts - General
- Spain Chart Of Accounts - PYMEs
- Spain Taxes
- Spanish Language for Spain
- Spanish Tax Module Improvements
- Spanish Tax Module Improvements - es_ES
- Validador de CIF y NIF - es_ES
- Modules: any other module developed by Openbravo (for modules NOT developed by Openbravo please use the corresponding bug tracker of the project in Openbravo Forge).
- Accruals and Deferrals
- Advanced Payments
- Booking Control
- Booking Process
- Business Partner Debt Consolidation
- Camerfirma Webservice
- Concepts - XmlEngine
- Direct Debit Form of Payment
- Electronic Invoice
- Electronic Invoice - es_ES
- Facturae 3.1
- Freemarker Templating Language
- HQL Query Tool
- Human Capital Management
- Initial data load
- Intercompany Documents
- JSON REST
- JSON Datasource
- Mass Advanced Payments
- Mass Invoicing
- Mass Ordering
- Multi-Business Partner Selector
- Orders Awaiting Delivery
- POS-ERP Synchronization Web Service
- Report Sales By Month
- Sample Modules
- Seam Integration
- Seam Richfaces
- Seam Test
- Shipments Awaiting Invoice
- Smartclient Integration
- Tax Report Launcher
- Tax Report Launcher - es_ES
- User interface Client Kernel
- Documentation: for any issue related to Openbravo ERP and Openbravo POS documentation.
- Contribution Requests: to track requests to contribute to the Openbravo core products or to sponsor new feature development.
- Localizers Support: to track requests for assistance from people working on localization issues.
- Tools: to track issues with the tools that Openbravo uses.
How to Report an Issue
This section contains a step by step guide and some good recommendations on how to properly report issues.
Before reporting a bug
Please, before reporting a new bug, make sure that:
- It is a bug. Ensure that your problem is a general problem and not due to your particular configuration. If you are not sure that the behaviour is correct, please post a comment in the most accurate forum. To check this, have a look at:
- The bug has not been already reported. If you have new information about an existing bug, please post a comment on the first bug - do not open a new bug report. To check this, have a look at:
- Use the latest version of the program. Before reporting a bug, make sure that you are using the latest version of Openbravo. This will minimize the chance of reporting a bug that has already been fixed. To check this, have a look at:
Quick guide to writing good bug reports
Software problems are sometimes complex issues. Writing a good issue report makes it easier for everyone (developers, testers, ...) to understand the problem and find a solution.
- ... is reproducible:
- ... is specific:
- Try and figure out exactly what causes the problem.
- Do not report more than one issue in the same report. You should report each issue in a different bug report.
- ... describes your environment:
- Include information about the versions of your Openbravo version, operating system, database system, Apache, Java runtime, Tomcat and other components which Openbravo relies on for its execution.
- ... provides a good summary:
- You should be as precise and clear as possible when you give a summary (also called title) to the bug report.
- Summaries like Program hangs or It doesn't work are bad samples of a title because they do not provide any indication of where or how the program fails.
- ... includes all the bug description fields:
- It helps a lot when managing the bug reports that users fill up the Category and Product Version fields.
- ... is not anonymous:
- Often developers need to contact the user to get additional information about the bug.
- If the bug reporter cannot be contacted, the developer may not have enough information to fix the bug.
Step by step issue reporting guide
- Are you sure that you are going to report a valid issue?
- If yes, navigate to https://issues.openbravo.com.
- Before you can report your issue, you need to login. If you do not have an existing username, you can signup for a new account.
- Start reporting your issue by clicking on Report Issue link at the top of the screen. You will be taken to the screen below.
- Make sure that you have chosen the right project on the top right of the screen. For example, if you want to report an issue about Openbravo ERP, make sure that Openbravo ERP is selected in the drop down list.
- You are now ready to start logging your issue by specifying the following attributes:
In case you just realized that you have entered into the wrong project and want to go to other project, then just change this option to the correct project.
Issue types are:
- Defect: for a defect with an existing feature.
- Feature Request: to request a new feature in the product.
- Design Defect: for a defect that requires an important redesign. If not sure, do not use this type.
- Backport: do NOT use this type when reporting issues.
This classifies the issues by area of impact. The list of categories depends on the project. Choose the category that you feel it is most representative of your issue.
Use this attribute to assess of the impact of this issue to the end user. The following values are possible:
Use this field to specify the degree of reproducibility of the issue:
- Does the bug reproduce consistently every time that some steps are followed?
- Is it a random bug? If so, please pay even more attention when describing the steps to reproduce the issue.
Expresses the order in which issues should be addressed by the resolving team.
Always use Normal priority when reporting an issue. This Normal priority is then altered based on:
- Subjective judgement of the Triage team.
- Defect cleaning campaigns: for instance, if we have special effort to correct labels that are not properly aligned, we might want to set priority to High for Trivial defects where a label is not properly aligned.
- Aging: in order to avoid defect stagnation, every once in a while, we increase the priority of the oldest defects in our queue.
While severity is assessed by the defect reporter and contributes to the assessment of the priority, it is only one of the contributing factors and, in the end, priority is assessed by the development team and reporters cannot change it.
For more information about how the Priority is set, check the page about determining the priority
Use this section to describe your environment:
- Operating System (OS)
- Operating System (OS) version
- Database version
- Java version
- Ant version
You can select either a pre-defined profile or specify individual values.
Choose the version of the Openbravo product you are experiencing a defect with. If you are using Openbravo ERP Developer's Edition building from sources out of source control, please select pi.
If you are reporting a defect on pi, please specify the revision or changeset you are using.
This contains a list of modules related to 3.0.
- So in case of reporting issue for module related to 3.0 then set this field to proper module (can leave it to Core if not sure about the module name) and version field to 3.0RC1 OR above).
- And in case of reporting as independent module (as done for any other module) then leave the version field blank.
Indicates whether the issue is reported by an Openbravo Professional Subscription Customer.
Developer that will be assigned the issue.
Expected resolution version for the issue.
A clear abstract of the issue. Summaries like Program hangs or It doesn't work are bad samples of a title because they do not provide any indication of where or how the program fails.
Steps To Reproduce
In case of defects, please provide detailed reproduction steps. Use numbering for a better understanding:
- Step 1
- Step 2
- Step 3
Optionally, you can suggest a solution to the problem.
- For defects, you can propose the expected behaviour or attach a fix patch.
- For feature requests, you can propose the behaviour desired.
How to Choose the Right Severity
The Severity attribute of an issue expresses the impact that the issue has on end user. It is different than Priority, which expresses the order in which issues should be addressed by the resolving team, but it is one of the factors that drive priority.
Severity is expressed by the reporter while Priority is controlled by the resolving team. While Severity is assessed by the defect reporter and contributes to the assessment of the Priority, it is only one of the contributing factors and, in the end, priority is assessed by the development team and reporters cannot change it.
Following list consist of some questions that may allow you to decide yourself the measure of severity.
- Does the system stop working after defect occurs?
- Does the system recover from the defect by any means?
- If the defect is recoverable, does the system require external effort to recover from the defect? (i.e. it will not recover on its own)
- Did I check whether the same defect is reflected in all other related sections (or entire system)?
- Can I be able to repeat the defect in some other system having same configuration (O/S, Browsers) as that of the system where I found the defect?
- Can I be able to repeat the defect in other configurations also?
- Does the defect affect all users? (i.e. Only a particular category of users will face the defect)
- Does the defect occurs frequently?
- Are the inputs to make the defect easy to get? (i.e. not special data has to be created)
The number of Yes on the previous questions should give you a good idea about the severity.
Some examples about severities can be found in the following list. Please have in mind that the list is not definitive, since other factors as the above conditions may increase or decrease what is marked following this table.
For example, "Page title missing" is listed as minor. But if it only happens under some circumstances, or only to some specific role, or on a specific browser version, the severity should be set as trivial.
For more information refer to How to determine the Severity.
| Issue Type|
Results in the failure of the complete software system, of a critical subsystem so that no work or testing can be carried out after the occurrence of the defect. It also applies to data loss failures and with processes that leave inconsistent data stored on the database.
Causes failure of entire or part of system, but there are some processing alternatives which allows further operation of the system. It also applies to the system crashing, or aborting, during normal operation of a non-critical flow.
Do not result in failure but causes the system to show incorrect, incomplete, or inconsistent results (note that show inconsistent results is way different of generating inconsistent results at database level as explained above). A critical usability issue fits also in this category, as well as if there is a simple workaround.
Small errors that do not prevent or hinder functionality, typos, grammar mistakes, wrong terminology, general usability issues and styling.
Proposing a bug fix
If you are a software developer and you have found a solution for the problem that you are reporting, you also can help Openbravo providing a fix for the problem and attaching your solution to the bug report. You can use the hg export or expose your repository in a public location. Before submitting the patch, remember:
- Make sure that your local copy is up-to-date (using hg pull -u).
- The patch should only fix the described issue. A patch fixing several issues makes its review process more difficult.
Resolving an issue
As a general rule defects should be solved by triggering actions from the Mercurial commits. For more information follow the Mercurial and Mantis integration user instructions.
If you can not resolve an issue by triggering an action from the Mercurial commits, just change issue status to Resolved, linking to the push done.
Rejecting an issue
If the issue has been rejected, you must indicate the reason why it has been rejected. For instance, the issue could be:
- Duplicated: specify the duplicate issue ID.
- Out of date: for issues that are not reproducing anymore.
- Not an issue: for defect reports which are describing a behaviour that is not a bug.
Rejected issues change their status automatically to Closed.
Sample Openbravo bug report
This is a sample bug report. Notice that it follows all of the indications that we have just described:
- it is reproducible,
- provides a good summary,
- includes all the bug description fields,
- provides detailed steps to reproduce it and
- it is not anonymous.
Steps to Reproduce:
Please NOTE that this is a Community Edition tool without any warranty to resolve issues. If you want to have predictable SLA you need to register tickets through Support Portal which is for Professional Edition only. For more on how to get/acquire Professional Edition please read this.