How to create a good bug report
Any complex piece of software will contain bugs and GRAMPS is no exception. Testing before a new release is made allows us to identify and fix all of the obvious bugs, however more obscure ones will inevitably make it into the final release. Reporting bugs is one of the best things that GRAMPS users can do to help the project improve the software, but the developers only have a chance to fix bugs if they can reproduce the bugs themselves. This can be difficult and time consuming for more obscure ones. It's important to realise that a good bug report which easily allows a developer to reproduce the bug is more likely to get the developer's attention and the bug fixed. This page describes how to make a good bug report.
Creating a test database
The GRAMPS developers do not have access to a user's computer or database and for data privacy reasons a user is normally unwilling to send a copy of their database to a developer. Bugs that cause data corruption usually mean that the symptoms of the bug are only visible in the user's database. To work around this problem, each installation of GRAMPS comes with a small set of example data which you can use to create a test database in which you can try and reproduce the bug yourself. If you can reproduce the bug in the test database and you record the steps taken to producing the bug then there is a good chance that a developer can do the same. Here is how to create yourself a test database.
- Open the Family Tree Manager and create a new database
- Import the example data set into your empty new database. You will find the example data in a file called example/gramps/data.gramps. The actual location of the top level "example" directory will depend on where you have installed GRAMPS on your system, though typically you will find it at /usr/share/gramps/example if you have installed GRAMPS from a package.
The example data set contains people, families and events that you can use to try and reproduce the problem.
Reproducing the bug
Bugs come in many different shapes and sizes. Some bugs just cause unexpected behaviour. Others are more serious and can cause GRAMPS to crash. The worst bugs are those that cause some data corruption in the database. Identifying the source of the bug is the hard part because the problem you see might just be a symptom of the bug and not the actual bug itself. These types of bugs often don't show any signs when the corruption is occurring. You only notice the symptoms of the bug when another part of GRAMPS tries to use the corrupted data. Here are some tips to help you reproduce the bug. If you succeed in getting the test database to cause the same symptoms then record the sequence of steps it took you to reproduce the problem.
- The first thing to try in your test database is to simply do whatever you did in your own database that caused the bug symptoms to occur. For example, if you crashed your own database running a report on a person then pick a person in the test database and run the same report there.
- Try performing some of the typical editing actions you perform on your own data and then run whatever action causes the symptoms to occur. Try doing things like adding and removing children from families. Try adding and removing events, sources and notes. Maybe you have performed one of these actions in your own database and there is a bug that has caused some data corruption that has gone unnoticed.
- The next thing to look at is the types of data you have been putting in your own database. Perhaps the problem is related to something unusual that you have added that GRAMPS cannot handle. With this type of problem you might find in your own database that GRAMPS shows the bug symptoms with one person, family, event (or whatever) but not another. Try and reproduce the same types of data in your test database and see if you get the same symptoms.
- Don't be afraid to delete and re-create your test database to keep it fresh. What you should be aiming for is to reproduce the bug with the minimum number of changes to the pristine example data set.
Recording the steps that reproduce the bug
When you have reached the point where you can consistently re-create your problem using your test database you should then open a bug report and document the steps you took to produce the problem. Make sure that you record your instructions in explicit detail so that a developer can follow your exact steps. State which people, families etc that you are using by quoting their Gramps ID.
Here is a sample bug report recording each step taken to reproduce a bug.
1) Create a new database and import "example" data set. 2) Click Person View tab.
More to come...