Bug Reporting Guidelines

Introduction

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.

Issue Classification

Openbravo uses two classifications for issues:

1. Issue Type
2. Project

Issue Type

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

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
  • Packs:
    • Openbravo 3.0 Framework
  • 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
      • Hello World
      • Hello World Process
      • Hello World Service
      • Sample Report
      • Skin Module Example
      • Solitaire
      • User Interface Selector Example
    • Seam Integration
    • Seam Richfaces
    • Seam Test
    • Selector
    • 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.
  • Infrastructure: to track issues with the Openbravo web sites.
  • Mantis @ OB
  • QA

How to Report an Issue

This section contains a step by step guide and some good recommendations on how to properly report issues.

Important Note: Remember issues.openbravo.com is a public website. In order to fulfill the GDPR please do not expose any information related to the customer in the ticket.

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.

• 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:
  • Openbravo Issues tracker
  • Openbravo Issues Google Custom Search

• 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:
  • Openbravo ERP live builds
  • Openbravo ERP demo

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.

Based on Mozilla and Simon Tatham bug writing guidelines, a good bug report always...

• ... is reproducible:
  • If the developers cannot reproduce it or conclusively prove that it exists, they probably will not be able to fix it, and move on to the next bug.
  • Provide step-by-step instructions for reproducing the bug for a quicker resolution.
  • Attached or linked videos and screenshots are welcome.

• ... 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

View larger

1. Are you sure that you are going to report a valid issue?
2. If yes, navigate to https://issues.openbravo.com.
3. 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.
4. Start reporting your issue by clicking on Report Issue link at the top of the screen. You will be taken to the screen below.
5. 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.
6. You are now ready to start logging your issue by specifying the following attributes:
   1. Project
   2. Type
   3. Category
   4. Severity
   5. Reproducibility
   6. Priority
   7. Profile
   8. Product Version
   9. SCM revision
   10. Modules
   11. OBNetwork customer
   12. Assign To
   13. Target Version
   14. Summary
   15. Description
   16. Steps To Reproduce
   17. Proposed Solution
   18. Upload File

Project

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.

Type

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.

Category

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.

Severity

Use this attribute to assess of the impact of this issue to the end user. The following values are possible:

• Trivial
• Minor
• Major
• Critical

See How to Choose the Right Severity section for more details.

Reproducibility

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.

Priority

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

Profile

Use this section to describe your environment:

• Operating System (OS)
• Operating System (OS) version
• Database
• Database version
• Java version
• Ant version

You can select either a pre-defined profile or specify individual values.

While this section is optional, it is important to specify your environment configuration especially if you are reporting a defect that you suspect might be platform dependent.

Product Version

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.

This field is optional but you should populate it when reporting a defect.

SCM revision

If you are reporting a defect on pi, please specify the revision or changeset you are using.

Modules

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.

OBNetwork customer

Indicates whether the issue is reported by an Openbravo Professional Subscription Customer.

To be ticked only by Openbravo Professional Subscription Customers.

Assign To

Developer that will be assigned the issue.

Unless you want to assign this issue to you, leave this field blank.

Target Version

Expected resolution version for the issue.

To be completed only by Openbravo Professional Subscription Customers.

Summary

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.

Description

A detailed description of the issue. The error log pasted or attached helps a lot.

Steps To Reproduce

In case of defects, please provide detailed reproduction steps. Use numbering for a better understanding:

1. Step 1
2. Step 2
3. Step 3
4. ...

You can also record the steps that you follow and attach or paste a link to the video.

Proposed Solution

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.

Upload File

You can use this field to attach to your issue error log file, screen shots or any other file you think might clarify your report.

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.

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,
• specific,
• provides a good summary,
• includes all the bug description fields,
• provides detailed steps to reproduce it and
• it is not anonymous.

Environment Provides Openbravo ERP, database, operating system, JDK, Tomcat and Ant versions. Category [Openbravo ERP] 08. Project and service management Summary ExpenseSOrder and RequisitionToOrder processes fail in PostgreSQL Description ExpenseSOrder and RequisitionToOrder processes fail in PostgreSQL because in their XSQL, date passed to M_GET_OFFERS_PRICE function do not have a to_date(). Steps to Reproduce: Create an Expense Sheet. Create an Expense Sheet Line (with Reinvoicing ticked) and select a Business Partner Go back to Expense Sheet header and process this expense. Create Sales Order from Expenses for the Business Partner. In the log, message 'ERROR: function m_get_offers_price(timestamp with time zone, numeric, numeric, numeric, numeric, numeric) does not exist' displays.

Disclaimer

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.