View source for How to create a good bug report

{{man tip|Before you create a "Bug" report...|Composing a bug report can involve a lot of research and writing effort. Save yourself from unnecessary work.

* A solution or workaround might already exist in another bug report or in the forums.
* If you cannot find anything resembling your issue, ask about it in one of the forums. The community will help you solve or isolate the problem.
* If using an [[Previous_releases_of_Gramps|older Gramps version]], please mention that you have also tested with the current Gramps {{version}} version and that the issue is present.}}


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.

Such a report can then be submitted on the bug tracker: [https://gramps-project.org/bugs/ https://gramps-project.org/bugs/]

==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, you can try and reproduce the bug yourself using a test database.  Each installation of Gramps comes with a small set of example data that you can use to create this test database.
 
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 your test database.

# Open the Family Tree Manager and create a new database.
# [[Example.gramps|Import the example data set]] into this empty, new database. You will find the example data in a file called example/gramps/data.gramps. The actual location of this directory will depend on where you have installed Gramps on your system, the previous link contains those details.

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.

Use your systems "screenshot" function to take any images that may help to explain the problem.

Here is a sample bug report recording each step taken to reproduce a bug.

# Create a new database and import "example" data set.
# Click Person View tab.
# Select Martin Smith (Gramps ID I39)
# Click Relationship View tab
# Click the edit button for Hanna Smith (Gramps ID I11)
# In Person Editor for Hanna Smith, doubleclick the birth event
# In Event Editor, change the birth year from 1821 to 1820
# Click OK in Event Editor
# Click OK in Person Editor
# Gramps crashes with the following error:

  Traceback (most recent call last):
  File "/home/gramps2/trunk/src/DisplayTabs/_EmbeddedList.py", line 440, in rebuild
    self.model = self.build_model(self.get_data(), self.dbstate.db)
  File "/home/gramps2/trunk/src/DisplayTabs/_ChildModel.py", line 61, in __init__
    child.get_gramps_id(),
  AttributeError: 'NoneType' object has no attribute 'get_gramps_id'

==See also==
* [[Using the bug tracker]]
* Help the Gramps project [[Bug triage]].
* [https://gramps.discourse.group/t/media-missing-from-events-in-narrated-web-site-and-complete-individual-report/4519/4 How to export a small sampling of your tree]

[[Category:Developers/General]]
[[Category:Developers/Quality Assurance]]
[[Category:How do I...|B]]