wiki:SubmittingBug

Writing a good bug report into the Vaadin bug tracker

I'm sure all developers have read bad bug reports. Don't write bad bug reports. Bad tickets only waste developers time and yours too. What is interesting here is that worst tickets are often created by experienced programmers. Writing a decent bug report do take some time, but writing a bad one will only waste it.

If you haven't heard about bad tickets before, please read the following story before continuing any further.

http://www.chiark.greenend.org.uk/~sgtatham/bugs.html

Writing a bad bug report for Vaadin is even easier than for a normal software project. There are several factors that may arise the issue and it is often very hard to reproduce the issue by developer. Test case and clear instructions to produce the bug becomes very important.

Characteristics of a good Vaadin bug report

It is NOT a duplicate

The very first thing to do before filling a bug report is to search for duplicates. Quick search in trac (top right corner) is fast and efficient for this. It is very likely that searching for duplicats will save also your time. If it is already there, don't add a new one. If you have some more details, better test case or a patch to fix it - add your contribution to existing ticket.

It is NOT outdated

Please, verify that your ticket exists with the latest available release or even better - with the latest code from svn. Vaadin is under very active development and it is possible that the bug you detected is already fixed, especially if you are using an outdated version.

One issue per ticket

If you have multiple issues, fill separate tickets of them. Possible relation (if you are not sure) can be typed into a description or a comment.

Clear description

What is the bug, how to produce it. Check out the above article for more information about good bug reports. If the bug is a regression, it is good to write down on which version it has worked.

Test case

A good bug report always has a test case. An exception is if there is an existing test case in com.vaadin.tests that demonstrates the bug. In that case the full name of the test case should be mentoined.

A test case is what framework developer always needs before fixing a bug. Your program code and instructions to produce the bug is a test case, but a really bad one. A good test case is reduced to minimum amount of code needed to reproduce the problem. Strip down all extra components and logic, custom themes etc. It is a bit time consuming task, but it needs to be done anyway. With a good luck you will find a bug in your code at this point.

Add your test case as an attachment to ticket or if you happen to got svn commit access, add it to an appropriate package below com.vaadin.tests.components.

If you're unable to create a good test case for some weird issue (e.g "this happens now and the when I do this quickly"), please try to discuss the issue on the forums instead of submitting a ticket; describe your issue - you'll probably get additional questions, and ultimately either a solution or an added ticket. This way you won't get a 'invalid' or 'wontfix' due to a fuzzy bug description. It's never wrong to discuss an issue on the forum before submitting a ticket.

Versions

Select the vaadin version you use in the "version" field. If you are using a nightly version, please write the full version in the ticket description.

Depending on the type of the bug there may be various dependent software that are related. This information may be required to repeat the bug. If you don't know exactly where the bug lies, it is safest to put them all to ticket. These include:

  • client OS
  • client browser
  • servlet container
  • server OS

Additional fields

Leave the milestone field empty. Milestone is used for scheduling the tickets to releases.

Patch (Optional)

If you have found the bug, it is often tempting to try fixing it. Please, do so. If you believe you created a valid fix for the bug please create a patch and add it as an attachment. This is the optimal case and you will often get your fix into release faster. Toolkit developers can then just validate the issue, review the change set and apply the patch.

Before creating a patch, please read the instructions: CreatingPatch

Other trac tickets

Enhancements/ feature request can also be filled into trac. But do not fill them as bugs (type=defect), but enhancements or tasks.

Last modified 8 years ago Last modified on 28 Aug 2009 13:47:19