How to report bugs

From gvSIG CE Wiki

Jump to: navigation, search

For a community-driven project such as gvSIG CE, feedback from users is very important. In the area of finding and fixing unexpected and erroneous software behavior ("bugs"), it is vital.

Since we do not have a formalized procedure and dedicated human resources for quality assurance, we strictly depend on active peer review ("bug hunting") by the community. So if you find a problem with gvSIG CE: Don't keep it to yourself. Instead, sign up to our bug tracker and commit a quick report there. This won't take much of your time and will ensure that problems can be replicated, understood and fixed by our developers.

BugTracker1.png

This page will guide you through the steps to open an account on the gvSIG CE bug tracker and report bugs or missing features. We have chosen MantisBT as our bug tracking software, because it has a particularly clean and simple user interface.

Contents

Registration

Update (2014-10-12): Due to abuse by spammers, new user accounts will be limited to a Viewer role by default.

Before you can use the bug tracker in earnest, you need to register. Registration on the bug tracker is free (of course!), fast and simple. All that is required is a valid email address. This will be used strictly so that the system can inform you if someone has picked up your bug report (aka ticket), commented on it, or even resolved the problem.

Note: Often, developers will have additional questions if they cannot quite replicate the problem. So it is important that you provide a working email address that you check frequently.

Just browse to http://bugs.gvsigce.org/, then click on "Signup for a new account".

Then follow the instructions to create a new account and watch your inbox for the confirmation message that the system will send you. Follow the instructions in the confirmation email and you will have a working account. Note that this account will be limited to a "Viewer" role at first. That means you will not be able to add or change tickets. We had to do this to protect our tracker from spammers. If you wish to report a bug, contact us via any of the mailing lists.

Once your account has been promoted to "Reporter" status, you can add or change tickets. To do so, log into the bug tracker (you may need to browse to http://bugs.gvsigce.org/ once more) and continue with the next section to learn how to file and edit bug tickets.

Usage

The gvSIG CE bug tracker is based on MantisBT which is a wonderful piece of open source software that is really easy to use. Here, we will give you a short introduction on how to file a bug ticket using our tracker.

Filing new tickets

Chances are that you have come to the bug tracker for the first time, because you want to report a problem or a missing feature. This is a straight forward procedure.

General notes

  • After logging, in select whether your report is for gvSIG CE or SEXTANTE by setting the "Project:" field on the top right of the screen accordingly.

BugTracker project.png

  • Before writing a new report, check if your problem has already been reported (see next section on "Reviewing/editing tickets").

Report details

You will now be taken to a page titled "Enter Report Details". The following is a list of fields you need to set. Leave everything empty for which you have no information. You can always come back later and edit your report further.

  • Category: Select the part of gvSIG CE which your issue relates to from a list of predefined choices.
  • Reproducibility: Issues appear always, frequently or sporadic. Set this field accordingly.
  • Severity: You will probably want to leave this and the Priority field as-is. The decision, which issues should be treated first and are the most severe usually take some time to be made. If you are reporting a missing feature (not a bug), then set this to "feature". If you are suggesting a small improvement, set it to "tweak".
  • Priority: See above.
  • Select Profile: Here you select which operating system you run gvSIG CE on.
  • Product Version: Enter the version of gvSIG (CE) that you have observed the issue on.
  • Assign To: Leave as-is, unless you are sure that a specific developer has agreed to look after this issue.
  • Target Version: You can set this to the next planned release version number of gvSIG CE. Later, it may be decided to delay resolving the issue for another version. If you aren't sure which version you should choose, please set the target version as "unspecified". Only the tickets with an assigned target version will appear in the roadmap.
  • Summary: A one-line summary (title) of the problem. Try to mention the specific affected tool.
  • Description: Give a concise, but precise description of the problem.
  • Steps To Reproduce: Write down the tools you used before the problem appeared.
  • Additional Information: Anything else you feel might be important about the problem.
  • Upload File: Here you can attach helpful files (e.g. sample data) with a maximum size of 2 MB.

Note: If you are reporting a "feature" or "tweak", then set the "Reproducibility" field to "N/A".

Then press "Submit Report". This will save your report and send a notification email to all users of the bug tracker to inform them about the new ticket.

Reviewing/editing tickets

Press "View Issues" to get a concise list of all reports that are currently in the bug tracker. You will notice that there are many options on this page to filter and sort the tickets. You will also see each ticket's status and whether it has already been picked up by ("assigned to") a developer to take care of it.

  • If you wish to revisit a ticket that you filed earlier and edit it, then click on the little pencil icon BugTracker update.png in its row.
  • If you wish to add information to someone else's ticket or add a note to one of your own, click on the ticket's "ID" number. Then write your note in the field under "Add Note" and click "Add Note" to submit your changes. Other users will be notified of this.

BugTracker notes.png

  • Important: If you believe that a ticket is related to, or even a duplicate of, another ticket, then you should also report that. Click on the ticket's "ID" number to edit its details. Find the "Relationships" details. Here, you can set the type relationship and enter the ID number of the related ticket. Then press "Add".

BugTracker relationships.png

Reporting problems

Knowing how to use the bug tracker is a good start, but you need to know more if you want a good chance that the bug you found can be dealt with. Fixing bugs is by no means an easy or automatic procedure. Just to give you an idea about the scope of this: Our developers need to navigate through more than 1.5 million lines of Java source code to spot the one or two bad lines that may be causing the program to misbehave!

So the essential first step towards solving a problem is to communicate and write a good bug report. In this section, we have collected some advice. Observe it and your bug tickets will be more useful and easier to understand. But first, let's review some etiquette.

Even if you don't want to write a bug report (yet), but are looking for help via our mailing lists, or forums: pleased read the following two sections on "Etiquette" and "the gvSIG log file".

Etiquette

As you can imagine, dealing with bugs can be a complex, sometimes frustrating procedure. It is not exactly the sort of thing most programmers would like to spend their time on. So please observe the following rules when reporting bugs, be it to the mailing list or bug tracker.

  • Rule #1: Our software works/runs!: You can assume that gvSIG (CE) is a software that does, indeed, work and run on thousands of computers. Messages carrying the text "gvSIG CE is not working" will not get you anywhere. Instead, write what part of it exactly does not work (for you), and someone might be able to help.
  • Rule #2: No pressure, please!: Do not attempt to transfer your own time pressure to other people. Communications like "Please help fast, I have to finish my project soon!" are not likely to win you many friends. You alone are responsible for your own time planning. If it fails, blame yourself, but never attempt to pressure others for it.
  • Rule #3: Take your time if you want theirs!: "plz hlp, got problem." is not an acceptable form of communication. At least not if you want someone to potentially invest hours into reproducing the problem you have found and fixing it. Please take enough time to write proper English sentences, if only as a sign of respect.
  • Rule #4: Use available resources first!: Often, an apparent bug is really a slight "mis-understanding" between software, data and user. We have very active mailing lists and a forum where you can always post first. Our mailing lists also get archived, so Google is your friend for retrieving answers to problems that have been discussed before.
  • Rule #5: Trust them to notice!: All gvSIG developers read the messages to the mailing lists, forum entries and bug tickets. If they have the time/knowledge to provide a solution, they will. Emailing developers directly will not improve your chances of getting your bug fixed.

The gvSIG log file

One of the most important tools for fixing bugs is the gvSIG log file, gvSIG.log. This is a text file which exists in the gvSIG subfolder of your user folder. Its precise location differs between operating systems. In recent Windows versions, it is by default stored in C:\Users\<user-name>\gvSIG (i.e. in the same folder where all your program settings are also stored). Can't find it? Use your system's file search tool to locate gvSIG.log!

This log file will contain a full transcript of all warning and error messages that appeared when the program misbehaved. Please make a copy it right after the problem appears, and before you close gvSIG or attempt to do anything to fix the error, then attach that copy to your email or bug report.

Ticket contents

  • The best way to make sure that a ticket gets filled in properly is to simply work from top to bottom. Sometimes, you may be uncertain about how to fill in some fields. That's OK. Simply provide all the information you have. All subscribers to the bug tracker will be notified and other people may be able to fill in the missing bits for you, or will get back to you about them. In any case, it's better for the developers to have partial information about a problem than none at all! By getting feedback from other users of the bug tracker, you will learn very quickly how to provide complete reports.
  • When phrasing your tickets, please be as precise as you can in stating your problem. Pay special attention to the ticket Summary (title). A good title can make understanding the purpose of a ticket a lot easier. Try to mention the name of the particular gvSIG tool or component at the beginning of the ticket title.
  • One of the central issues with bug tickets is the matter of reproducibility. In order to have any chance to fix bad program behavior, it must be possible for someone else to take the same (or similar) data, run the same program function and observe the same error. For this reason, there is a separate section in each bug report, labeled "Steps To Reproduce", where you can describe exactly the steps to perform in order to reproduce the problem. Some problems are of a sporadic nature, i.e. they only happen sometimes and are hard to reproduce. Set the "Reproducibility" field (at the top of the report) accordingly.
  • You can also upload and attach datasets or error log files (gvSIG.log: see above) to a ticket. But please be aware that the size limit per upload is about 2 MB.