How to create a good bug report - Revision history

Patsyblefebre: Category:Developers/Quality Assurance

2013-01-22T04:09:00Z

Category:Developers/Quality Assurance

Patsyblefebre: Gramps

2013-01-22T04:06:46Z

Gramps

Daleathan: /* Recording the steps that reproduce the bug */

2011-06-20T13:05:59Z

‎Recording the steps that reproduce the bug

Gioto: need a simpler version of this

2010-12-22T22:36:22Z

need a simpler version of this

Bmcage at 12:25, 22 January 2009

2009-01-22T12:25:36Z

Gburto01: Add sample bug report.

2008-08-11T20:19:42Z

Add sample bug report.

Gburto01: Wrong file name

2008-08-11T20:09:01Z

Wrong file name

Gburto01: Revised text

2008-08-11T12:13:19Z

Revised text

Gburto01: /* Recording the steps that reproduce the bug */

2008-08-08T12:56:05Z

‎Recording the steps that reproduce the bug

Gburto01: 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...

2008-08-08T12:51:30Z

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...

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 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/example.gramps. The actual location of the top level "example" directory will depend on where you have installed GRAMPS on your system.

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 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.

An example to follow ....

← Older revision		Revision as of 04:09, 22 January 2013
Line 50:		Line 50:

	[[Category:Developers/General]]		[[Category:Developers/General]]
		+	[[Category:Developers/Quality Assurance]]

@@ Line 1: / Line 1: @@
-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: [http://bugs.gramps-project.org/ http://bugs.gramps-project.org/]
 ==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, 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.
+# 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.
+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.
@@ Line 18: / Line 18: @@
 * 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.
@@ Line 47: / Line 47: @@
 ==Bug triage==
-Help the GRAMPS project [[Bug triage]].
+Help the Gramps project [[Bug triage]].
 [[Category:Developers/General]]

@@ Line 44: / Line 44: @@
      child.get_gramps_id(),
    AttributeError: 'NoneType' object has no attribute 'get_gramps_id'
 [[Category:Developers/General]]

@@ Line 1: / Line 1: @@
 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.
@@ Line 45: / Line 44: @@
      child.get_gramps_id(),
    AttributeError: 'NoneType' object has no attribute 'get_gramps_id'

@@ Line 26: / Line 26: @@
 Here is a sample bug report recording each step taken to reproduce a bug.
-) Create a new database and import "example" data set.
+# Create a new database and import "example" data set.
-) Click Person View tab.
+# Click Person View tab.
-More to come...
+  Traceback (most recent call last):

@@ Line 6: / Line 6: @@
 # 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/example.gramps. The actual location of the top level "example" directory will depend on where you have installed GRAMPS on your system.
+# 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, 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.
@@ Line 22: / Line 22: @@
 ==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 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 ....
+Here is a sample bug report recording each step taken to reproduce a bug.