Bug Reporting Guidelines

Contents 1 Introduction 2 The Issue Life Cycle 3 Issue Classification 3.1 Issue Type 3.2 Projects 4 How to Report an Issue 4.1 Before reporting a bug 4.2 Quick guide to writing good bug reports 4.3 Step by step issue reporting guide 4.3.1 Type 4.3.2 Category 4.3.3 Severity 4.3.4 Reproducibility 4.3.5 Priority 4.3.6 Profile 4.3.7 Product Version 4.3.8 SCM revision 4.3.9 Assign To 4.3.10 Target Version 4.3.11 Summary 4.3.12 Description 4.3.13 Steps To Reproduce 4.3.14 Proposed Solution 4.3.15 OBNetwork customer 4.3.16 Upload File 4.4 How to Choose the Right Severity 4.5 Proposing a bug fix 5 Resolving an issue 6 Rejecting an issue 7 Sample Openbravo bug report

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.
• 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 defects from 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 and as defects and feature requests should be handled differently. In particular, defects should be resolved at the earliest opportunity while feature requests require planning, design and therefore need to be explicitly scheduled for a given release.

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
  • 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
    • HQL Query Tool
    • Human Capital Management
    • Initial data load
    • Intercompany Documents
    • Mass Advanced Payments
    • Mass Invoicing
    • Mass Ordering
    • Multi-Business Partner Selector
    • Openbravo JSON REST
    • Openbravo Seam Integration
    • 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
    • Shipments Awaiting Invoice
    • Tax Report Launcher
    • Tax Report Launcher - es_ES
• 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.

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:
  • Openbravo ERP forums
  • Openbravo POS forums

• 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

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. Type
   2. Category
   3. Severity
   4. Reproducibility
   5. Priority
   6. Profile
   7. Product Version
   8. SCM revision
   9. Assign To
   10. Target Version
   11. Summary
   12. Description
   13. Steps To Reproduce
   14. Proposed Solution
   15. OBNetwork customer
   16. Upload File

Type

Issue types are:

• Defect: for a defect with an existing feature.
• Feature Request: to request a new feature in the product.
• 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

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 issues reported by Openbravo Professional Subscription Customers, the Priority is set to Immediate, regardless of the severity.
• For other issues:

Severity	Priority
Critical	Urgent
Major	High
Minor	Normal
Trivial	Low

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.

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.

SCM revision

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

Assign To

Developer that will be assigned the issue.

Target Version

Expected resolution version for the issue.

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.

OBNetwork customer

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

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.

It is important that, as a reporter, you choose the appropriate severity. You can use the following guidelines.

Issue Type Severity Level	Defect	Feature Request
Critical	Product does not build. Production system is severely impacted or completely down. System operations or business-critical applications are down.	Do not use this severity for feature requests.
Major	The production system is functioning with limited capabilities. The production system is unstable with periodic interruptions. Mission critical applications, while not being affected, have experienced material system interruptions. There is a time sensitive question impacting performance or deliverables. A major subsystem under development is blocked.	New functionality that would significantly increase the user base of the product. Usability improvements.
Minor	There are errors causing partial, non-critical functionality loss. One which impairs some operations but allows the customer to continue to function. There is a need to clarify procedure or information in documentation. There are errors in system development that may impact performance deliverables.	New feature or revision of existing feature that would significantly improve the usefulness of the product. New feature that would improve the internal qualities of the product.
Trivial	There are errors in system development that that have little to no impact on performance deliverables. There is a request for a product enhancement.	New feature or revision of existing feature that would marginally improve the usefulness of the product.

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.

Category: Quality Assurance ERP