Difference between revisions of "Using the bug tracker"

From Gramps
Jump to: navigation, search
m
m (MantisBT)
 
(92 intermediate revisions by 11 users not shown)
Line 1: Line 1:
{{languages|How to report bugs}}
+
{{languages|Using the bug tracker}}
The bug/issue tracker for GRAMPS is located at the following URL: http://bugs.gramps-project.org
+
{{man tip|The bug/issue tracker for Gramps|is located at the following URL: <code>https://www.gramps-project.org/bugs</code>}}
 
This bug/issue tracker allows users and developers to log new issues and track them as they progress. Please take some time to read the issue tracker instructions below and read '''[[How to create a good bug report|how to create a good bug report]]'''. Also, have a look at '''[[Known_issues|known issues]]''' and '''[[Common_problems|common problems]]'''.
 
This bug/issue tracker allows users and developers to log new issues and track them as they progress. Please take some time to read the issue tracker instructions below and read '''[[How to create a good bug report|how to create a good bug report]]'''. Also, have a look at '''[[Known_issues|known issues]]''' and '''[[Common_problems|common problems]]'''.
 +
 +
== Quick recommendations ==
 +
When composing a problem (bug) report for Gramps:
 +
* Be '''''precise'''''
 +
* Be '''''clear''':'' explain how to reproduce the problem, step by step, so others can reproduce the bug, or understand the request.
 +
* Include only '''''one problem per report'''''
 +
* Include any relevant links and '''''examples'''''
 +
{{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.<ul><li>A solution or workaround might already exist in another bug report or in the forums.</li><li>If you connot find anything resembling your issue, ask about it in one of the forums. The community will help you solve or isolate the problem.</li></ul> }}
  
 
==Report a bug==
 
==Report a bug==
 
===1. Login===
 
===1. Login===
To report a bug, you must have a login account on http://bugs.gramps-project.org, which is the GRAMPS bug tracker. When you create a user account, remember that it can take up to 12 hours before a notification email is send to you. Only after clicking on the link in the email can you submit bugs. Your email address will be handled confidentially.
+
To report a bug or raise a feature request, you must have a login account on the '''Gramps bug tracker''' ''([https://www.mantisbt.org/ powered by MantisBT])'':
 +
* [https://bugs.gramps-project.org {{man button|Login}}] to your account at https://gramps-project.org/bugs/login_page.php , or;
 +
* Select [https://gramps-project.org/bugs/signup_page.php {{man button|Signup for a new account}}] or visit the following link to create a new login account: https://gramps-project.org/bugs/signup_page.php .
  
===2. Search existing bugs===
+
Due to periodic SPAMbot activity, New Account requests might require human pre-approval. Be aware that this means that it might take up to 12 hours before a confirmation email is sent when creating a user account. Only after clicking on the link in the confirmation email can you submit bugs. Your email address will be handled confidentially.
Perhaps the bug you want to report has been submitted before. To check this, click on 'View Issues'. The top of the page is reserved for filters, which you set. Normally the default filters are just fine. Under these filters, there is a search box. Enter the terms best describing the bug, and click apply filter. If you have an error message, try pasting a part of the error, to see if it is has been reported already.
 
  
If the bug is already reported, read the bug report over, and see if you can add to the information. If so, you can leave a note with extra information to help the developers.
+
{{-}}
  
===3. Submit new bug===
+
===2. Search wiki and existing bugs===
Click on Report Issue, and enter the required information, see below on how to select the project to which the bug belongs. Be verbose, the developers are bad at mind reading. Do not forget to list the GRAMPS version you are using. You can check this in GRAMPS by clicking in the GRAMPS program the Help menu, option About.
+
[[File:Search box for existing bugs.png|thumb|right|450px|Search Box]]
 +
Sometimes the behavior being observed might seem odd, yet as-designed. So the first step is to search the wiki to see what the documented behavior is. If you're still not sure, ask the [https://forum.gramps-project.org/ Gramps community on Discourse.]
  
==== Projects ====
+
If it still appears to be a bug, perhaps the bug you want to report has been reported before. To check this, click on [https://gramps-project.org/bugs/view_all_bug_page.php {{man button|View Issues}}]. The top of the page is reserved for filters, which you set. Normally the default filters are just fine. Under these filters, there is a {{man label|Search}} box. Enter the terms best describing the bug, and click {{man button|Apply Filter}} to search. If you have an error message, try pasting a part of the error, to see if it is has been reported already.
In the upper right corner of the issue tracker, there is a place to select the "project" for the bugs. "Projects" are a way to categorize issues. There are three types of projects in the issue tracker:
 
  
#The '''Feature Requests''' project is a place for recording requests for new features.
+
If the bug is already reported, read over the bug report, and see if you can add to the information. If so, you can leave a note with extra information to help the developers.
#The projects with names that look like '''Gramps x.x.X''' are where issues are reported that apply specifically to a maintenance branch (see [http://www.gramps-project.org/wiki/index.php?title=Brief_introduction_to_SVN#Types_of_branches Types of Branches]). A separate project exists for each maintenance branch.
+
{{-}}
#The '''Gramps Trunk''' project should only be used by developers and testers of the latest code. It is a place for recording issues that only apply to the trunk in Subversion (see [http://www.gramps-project.org/wiki/index.php?title=Brief_introduction_to_SVN#Types_of_branches Types of Branches]). There is only one "Gramps Trunk" project because there is only one trunk in the Subversion repository
 
  
 +
===3. Submit new bug===
 +
[[File:Report issue buttons Gramps bugs.png|thumb|right|450px|'Report Issue' buttons.]]
 +
Click on one of the {{man label|Report Issue}} buttons, and enter the required information, see below on how to select the project to which the bug belongs. Be verbose, the developers are bad at mind reading. We shall mercilessly close the bugs which have no meaningful information at all, such as #{{bug|7126}}. Do not forget to list the Gramps version you are using. You can check this in Gramps by clicking in the Gramps program the Help menu, option About.
 +
{{-}}
 
==== How to proceed ====
 
==== How to proceed ====
The first step in submitting an issue on the tracker is to determine which project it belongs to.  
+
[[File:Dropdown-Choose-Project-GrampsBugtracker.png|thumb|right|450px|Choose Project - selection list]]
 +
The first step in submitting an issue on the tracker is to determine which project it belongs to on the issue tracker from the '''Select Project''' box, use the '''Choose Project''' drop down list to select the "project" for the bugs. "Projects" are a way to categorize issues. There are two types of projects in the issue tracker, '''Feature Requests''' and '''Gramps''':
  
*If the issue represents functionality that does not currently exist in GRAMPS, then the issue should be filed under the '''Feature Requests''' project.
+
*The '''Feature Requests''' project is a place for recording requests for new features.
 +
**If the issue represents functionality that does not currently exist in Gramps, then the issue should be filed under the '''Feature Requests''' project.
  
*If the issue represents a problem with functionality that has been released in a stable release of code, then the issue should be filed under the project that corresponds to the maintenance branch for that release. For example, a bug found in GRAMPS 3.2.6 should be filed under the '''Gramps 3.2.X''' project.
+
*The '''Gramps''' project is a place for recording all issues with Gramps.
 +
**If the issue represents a problem with functionality that has been released in a stable release of code, then the issue should be filed under the project that corresponds to the maintenance branch for that release. For example, a bug found in Gramps 5.1.0 should be filed under the '''Gramps 5.1.0''' project.
  
*If the issue represents a problem with functionality that only exists in trunk, or the problem exists in trunk, but not any stable releases, then the issue should be filed under the '''Gramps Trunk''' project.
+
*If the issue represents a problem with functionality that only exists in the master branch, or the problem exists in the master branch, but not any stable releases, then the issue should be filed under the Gramps Master projects next release number eg: 5.2.0 ( As shown on the MantisBT Roadmap page https://gramps-project.org/bugs/roadmap_page.php )
 +
{{-}}
  
== Resolving bugs ==
+
==== Enter Issue Details ====
This information is for the developers following up on the submitted issues.
+
[[File:Enter Issue Details page Gramps bugs.png|thumb|right|550px|Enter Issue Details - page]]
 +
The {{man label|Enter Issue Details}} page is where you share with the developers what your issue or feature request is.
  
In general, when resolving an issue, it is always a good idea to add a note with the SVN revision number of the commit that fixed the problem.
+
Try and complete all the relevant sections as well as you can and be prepared to answer follow up questions if your report needs clarification, it may help you to read the '''[[How to create a good bug report]]''' article.
  
When resolving issues in a maintenance branch, one should always set the "Fixed in version" field to the version of the next release that will be made from that branch. This is done so that the issue properly appears in the ChangeLog page for that project (http://bugs.gramps-project.org/changelog_page.php).
+
===== Filling out the page =====
  
Bugs in maintenance branch projects should not be marked as closed until the developer has committed the change into the corresponding maintenance branch. Additionally, it is the developers responsibility to make sure the change has been merged into trunk.
+
* Select Profile
 +
** Gramps runs on multiple operating systems, so it's helpful to know which operating system and version you are reporting an issue against. This is where you provide that information. MantisBT allows you store multiple profiles in your Account so that you can pick the appropriate one, which is handy if you run Gramps on different system configurations.
 +
* Product Version
 +
**The projects with names that look like '''Gramps x.x.X''' are where issues are reported that apply specifically to a maintenance branch (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]). A separate project exists for each maintenance branch.
 +
**The '''Gramps Master''' project should only be used by developers and testers of the latest code. It is a place for recording issues that only apply to the master branch in Git (see [[Brief_introduction_to_Git#Types_of_branches|Types of Branches]]). There is only one "Gramps Master" project because there is only one master branch in the Git repository.
 +
{{-}}
  
==Bug triage==
+
==Useful MantisBT bug tracker Syntax codes==
  
Help the GRAMPS project [[Bug triage]].
+
The following are useful [http://www.mantisbt.org/ MantisBT bug tracker] syntax codes you can use:
 +
* Using ''<code>#</code>'' before a bug number writes a link to the bug. eg: ''<code>#1</code>'' becomes {{bug|1}}
 +
* Use ''<code>@</code>'' before a user name to mention a person (note: user names with embedded spaces are not supported)
 +
* Using ''<code>~</code>'' before a comment number writes a link to the comment, same as : ''<code>{url}#c{comment number}</code>''. eg: ''<code>~3</code>'' becomes [https://gramps-project.org/bugs/view.php?id=1#c3]
 +
* To link a GitHub Pull Request in the bug tracker, use p:gramps:nnnn: where nnnn is the PR number.
  
==Syntax==
+
=== Limited HTML tags ===
 +
* A [https://github.com/mantisbt/mantisbt/blob/55fb5721ea7d980557da484390db5c6003b63cd0/config_defaults_inc.php#L1979 limited set] of [https://www.w3schools.com/tags/ HTML tags] can be used in the text field:
 +
**<code> &lt;p&gt; &lt;/p&gt;</code>  to define a paragraph.
 +
**<code> &lt;li&gt;</code> to defines a [https://www.w3schools.com/tags/tag_li.asp list item] used with:
 +
***<code> &lt;ul&gt;</code> unordered lists
 +
***<code> &lt;ol&gt;</code> ordered lists
 +
**<code> &lt;br&gt;</code> to insert a single line break.
 +
**<code> &lt;pre&gt; &lt;/pre&gt;</code> to add preformatted text, that is displayed in a fixed-width font, and it preserves both spaces and line breaks.
 +
**<code> &lt;i&gt;  &lt;/i&gt;</code> usually displays text in ''italics''.
 +
**<code> &lt;b&gt; &lt;/b&gt;</code> shows '''bold''' text
 +
**<code> &lt;u&gt; &lt;/u&gt;</code> Underline a misspelled word
 +
**<code> &lt;em&gt; &lt;/em&gt;</code> It renders as emphasized text.
 +
**<code> &lt;strong&gt;</code>  It defines important text.
  
[http://www.mantisbt.org/ Mantis bug tracker] uses its own syntax code :
+
==See also==
* ''#'' before a bug number writes a link to the bug.
+
* [[How to create a good bug report]]
* ''~'' before a comment number writes a link to the comment, same as : ''{url}#c{comment number}''.
+
* [[Known issues]]
* we can try to use some HTML tags into text field, like : <code> < pre >< /pre > < i > < / i > < b > < / b></code> 
+
* [[Common problems]]
 +
* Help the Gramps project [[Bug triage]].
  
 
[[Category:Developers/General]]
 
[[Category:Developers/General]]
 +
[[Category:Developers/Quality Assurance]]

Latest revision as of 22:57, 5 February 2023

Tango-Dialog-information.png
The bug/issue tracker for Gramps

is located at the following URL: https://www.gramps-project.org/bugs

This bug/issue tracker allows users and developers to log new issues and track them as they progress. Please take some time to read the issue tracker instructions below and read how to create a good bug report. Also, have a look at known issues and common problems.

Quick recommendations

When composing a problem (bug) report for Gramps:

  • Be precise
  • Be clear: explain how to reproduce the problem, step by step, so others can reproduce the bug, or understand the request.
  • Include only one problem per report
  • Include any relevant links and examples
Tango-Dialog-information.png
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 connot find anything resembling your issue, ask about it in one of the forums. The community will help you solve or isolate the problem.


Report a bug

1. Login

To report a bug or raise a feature request, you must have a login account on the Gramps bug tracker (powered by MantisBT):

Due to periodic SPAMbot activity, New Account requests might require human pre-approval. Be aware that this means that it might take up to 12 hours before a confirmation email is sent when creating a user account. Only after clicking on the link in the confirmation email can you submit bugs. Your email address will be handled confidentially.


2. Search wiki and existing bugs

Search Box

Sometimes the behavior being observed might seem odd, yet as-designed. So the first step is to search the wiki to see what the documented behavior is. If you're still not sure, ask the Gramps community on Discourse.

If it still appears to be a bug, perhaps the bug you want to report has been reported before. To check this, click on View Issues. The top of the page is reserved for filters, which you set. Normally the default filters are just fine. Under these filters, there is a Search box. Enter the terms best describing the bug, and click Apply Filter to search. If you have an error message, try pasting a part of the error, to see if it is has been reported already.

If the bug is already reported, read over the bug report, and see if you can add to the information. If so, you can leave a note with extra information to help the developers.

3. Submit new bug

'Report Issue' buttons.

Click on one of the Report Issue buttons, and enter the required information, see below on how to select the project to which the bug belongs. Be verbose, the developers are bad at mind reading. We shall mercilessly close the bugs which have no meaningful information at all, such as #7126. Do not forget to list the Gramps version you are using. You can check this in Gramps by clicking in the Gramps program the Help menu, option About.

How to proceed

Choose Project - selection list

The first step in submitting an issue on the tracker is to determine which project it belongs to on the issue tracker from the Select Project box, use the Choose Project drop down list to select the "project" for the bugs. "Projects" are a way to categorize issues. There are two types of projects in the issue tracker, Feature Requests and Gramps:

  • The Feature Requests project is a place for recording requests for new features.
    • If the issue represents functionality that does not currently exist in Gramps, then the issue should be filed under the Feature Requests project.
  • The Gramps project is a place for recording all issues with Gramps.
    • If the issue represents a problem with functionality that has been released in a stable release of code, then the issue should be filed under the project that corresponds to the maintenance branch for that release. For example, a bug found in Gramps 5.1.0 should be filed under the Gramps 5.1.0 project.
  • If the issue represents a problem with functionality that only exists in the master branch, or the problem exists in the master branch, but not any stable releases, then the issue should be filed under the Gramps Master projects next release number eg: 5.2.0 ( As shown on the MantisBT Roadmap page https://gramps-project.org/bugs/roadmap_page.php )


Enter Issue Details

Enter Issue Details - page

The Enter Issue Details page is where you share with the developers what your issue or feature request is.

Try and complete all the relevant sections as well as you can and be prepared to answer follow up questions if your report needs clarification, it may help you to read the How to create a good bug report article.

Filling out the page
  • Select Profile
    • Gramps runs on multiple operating systems, so it's helpful to know which operating system and version you are reporting an issue against. This is where you provide that information. MantisBT allows you store multiple profiles in your Account so that you can pick the appropriate one, which is handy if you run Gramps on different system configurations.
  • Product Version
    • The projects with names that look like Gramps x.x.X are where issues are reported that apply specifically to a maintenance branch (see Types of Branches). A separate project exists for each maintenance branch.
    • The Gramps Master project should only be used by developers and testers of the latest code. It is a place for recording issues that only apply to the master branch in Git (see Types of Branches). There is only one "Gramps Master" project because there is only one master branch in the Git repository.


Useful MantisBT bug tracker Syntax codes

The following are useful MantisBT bug tracker syntax codes you can use:

  • Using # before a bug number writes a link to the bug. eg: #1 becomes 1
  • Use @ before a user name to mention a person (note: user names with embedded spaces are not supported)
  • Using ~ before a comment number writes a link to the comment, same as : {url}#c{comment number}. eg: ~3 becomes [1]
  • To link a GitHub Pull Request in the bug tracker, use p:gramps:nnnn: where nnnn is the PR number.

Limited HTML tags

  • A limited set of HTML tags can be used in the text field:
    • <p> </p> to define a paragraph.
    • <li> to defines a list item used with:
      • <ul> unordered lists
      • <ol> ordered lists
    • <br> to insert a single line break.
    • <pre> </pre> to add preformatted text, that is displayed in a fixed-width font, and it preserves both spaces and line breaks.
    • <i> </i> usually displays text in italics.
    • <b> </b> shows bold text
    • <u> </u> Underline a misspelled word
    • <em> </em> It renders as emphasized text.
    • <strong> It defines important text.

See also