Bug Entry Guidelines

Documenting defects and enhancements is one of the most important contributions you can make to the community. These guidelines will help you provide information for teams and individual contributors complete and improve projects faster.

The Goal of Filing an Item in the Issue Tracker is to Provide Information!

When you file a defect or a work item, you are creating a message for other people. In order for them to understand the message, you must provide clear information.

Provide as Much Detail as Possible

  • Fill out as many fields as you can.
  • New defects should be assigned to Unassigned (defaults to this). 
  • Provide screen shots, log files, URL's and references to similar defects.
  • Include detailed steps to reproduce the issue.
  • Attach a Selenium script.
  • If you think someone might be confused as to why something is a defect, explain.
  • Refer to requirements or design documents where appropriate.
  • Include text from Admin -> View System Information
  • When possible, check to see if the problem occurred in an earlier build.
  • Include data like username, date, time, and details that make the problem easier to find
  • If you checked a log file and find nothing, include a comment like "Nothing in [logname].log."
  • You may want to try other scenarios and include the results.

    Example: "The problem only occurs in Firefox. IE 7 works correctly."

Make Sure You Keep the Item Up-to-Date

If you have an email thread, IM, Skype, or other conversation about the issue, ADD THE INFORMATION TO THE COMMENTS. The item in the Issue Tracker should be the central repository for information and status of an issue.

ALWAYS Check to See if Someone Else has Already Filed the Issue
Duplicate defects take up extra time. Try searching on terms and locating the defect. In some cases, you may even need to Re-open an old defect.


Opening Issues in the Issue Tracker

  1. Go to the Issue Tracker site
    • Log into the site.
    • If you do not have a login, you must Register.
  2. Use the query tool to determine if your issue has already been filed.
    • If you find the issue, read the defect and update it with any new information you may have.
  3. After you log in, you will see a list like the one below. Select the appropriate option for your issue (usually Defect). Note: you will not see all options until you log in.
  4. Fill out the fields as completely and accurately as possible.

What Information Goes into a Mifos Issue?

A bug report is generally broken down into several parts:

SUMMARY

Describe the bug, in approximately 60 or fewer characters. A good summary should quickly and uniquely identify a bug report. If you do not provide good information, an engineer cannot meaningfully identify your bug by its summary because they manage several issues.

Bad Summary:
Software fails or install problem with mifos are examples of bad summaries

Good Summary:
number of digits after decimal inconsistent on Account page

DESCRIPTION

You must provide very specific information in the description. It allows the teams to reproduce, investigate, and verify the fixes.

1) PROVIDE AN OVERVIEW

Provide a detailed expansion of the summary.

Example of good overview:
On the Accounts page, some transaction amounts have only one decimal after the amount, others have two. Since this is currency, we should be consistent and always display two decimals (or whatever is standard) after the amount-- even if the last digit is a zero.

Example of a bad overview:
went to page. decimals aren't right

2) STEPS TO REPRODUCE THE PROBLEM
Provide easy-to-follow steps that will trigger the bug. Include any special setup steps, login information, account information, and any other information that will make it easy to see the problem. Repro steps are very important because the developer needs to see exactly what's going wrong in order to fix the problem.

Good example:

  1. Click on "Create loan account" from the left nav
  2. Select any client and any loan product
  3. Create a loan account with interest = 10%
  4. Preview repayment schedule, then click "edit" and change interest rate to 12%
  5. View repayment schedule again

Bad example:

logged in and went to page. changed field. noticed decimals wrong.

3) RESULTS OF THE REPRO STEPS

Provide both the current, incorrect behavior AND what behavior you expect to see. Sometimes, you may want to explain why the behavior is not what you expect.

Actual result:

What the application did after performing the above steps - this information is often similar to the initial summary or description.

Expected result: What you think the application should have done. Knowing what you were trying to do helps the developer understand what went wrong.

Additional Information

In most bug reports-you also need to note the build, the browser, platform, and other details--but those items are not required for Mifos right now.

 

Priority

Assign a level of importance in this field to help determine the priority. This field is used by the mifos triage team to prioritize the issue.  Use these definitions to indicate the severity of the issue:

Blocker: Prevents work from getting done, causes data loss, or BFI ("Bad First Impression").
Critical: Workaround required to get stuff done.
Major: Like Critical, but rarely encountered in normal usage.
Minor: Developer concern only, API stability or cleanliness issue.
Trivial: Nice to fix, but in a pinch we could live with it.

 

Issue Assignment

Issues are automatically assigned based on sub-component, so you need not assign your bug to a specific developer.

Notification

If you want to receive email notifications when a bug is entered into the issue tracker, you can update your Profile on the Issue Tracker.

For more tips and advice about writing a clear bug, see:

last modified 2009-12-28 16:00