Difference between revisions of "How to create a good bug report"

From Gramps
Jump to: navigation, search
(New page: Category:Developers/General 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 ob...)
 
(Bug triage)
(13 intermediate revisions by 8 users not shown)
Line 1: Line 1:
[[Category:Developers/General]]
+
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.
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==
 
==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.
+
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.  
  
# Open the Family Tree Manager and create a new database
+
Here is how to create your test database.
# Import the example data set into your empty new database. You will find the example data in a file called example/gramps/example.gramps. The actual location of the top level "example" directory will depend on where you have installed GRAMPS on your system.
+
 
 +
# 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.
 
The example data set contains people, families and events that you can use to try and reproduce the problem.
  
 
==Reproducing the bug==
 
==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.
+
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.
 
* 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.
Line 17: Line 24:
 
* 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.
 
* 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.
+
* 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.
 
* 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==
 
==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 then you need to open a bug report and document the steps you take to produce the problem. Make sure that what 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.
+
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.
  
An example to follow ....
+
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]].
 +
 
 +
[[Category:Developers/General]]
 +
[[Category:Developers/Quality Assurance]]
 +
[[Category:How do I...|B]]

Revision as of 23:41, 23 September 2020

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/

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.

  1. Open the Family Tree Manager and create a new database.
  2. 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.

  1. Create a new database and import "example" data set.
  2. Click Person View tab.
  3. Select Martin Smith (Gramps ID I39)
  4. Click Relationship View tab
  5. Click the edit button for Hanna Smith (Gramps ID I11)
  6. In Person Editor for Hanna Smith, doubleclick the birth event
  7. In Event Editor, change the birth year from 1821 to 1820
  8. Click OK in Event Editor
  9. Click OK in Person Editor
  10. 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