How to file a bug report: Difference between revisions
Jump to navigation
Jump to search
(categories and link to new page about how to provide patches) |
No edit summary |
||
| (28 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
[[Category:EN]] [[Category:Development]][[Category:Wiki_Help]][[Category:HOWTO]] | |||
==Introduction== | ==Introduction== | ||
Software development is almost useless without testing, and that's true for Scribus as well, of course. Testing means using the software, especially development versions. For Scribus this is currently the | [[Image:Scribus-mantis-logo.png|200px|thumb|right|Scribus MantisBT @ [http://bugs.scribus.net bugs.scribus.net]]] | ||
Software development is almost useless without testing, and that's true for Scribus as well, of course. Testing means using the software, especially development versions. For Scribus this is currently the version{{Developmental-version}} series, which will one day become Scribus version 1.(stable-version + 2) bugs, for example v1.4 becomes v1.6. | |||
In both cases, the procedure is the same. There is a software called ''bug tracking system'', in Scribus' case this is [http://www.mantisbt.org/ Mantis]. A bug tracking system allows developers to keep track of, discuss and review bug reports and RFEs (requests for enhancements). If you want to help to improve Scribus or absolutely need a feature, you are advised to use it. | Bugs, when discovered, need to be reported to let the developers know that something's wrong or at least seems to be wrong, so the problem can be fixed, if necessary. Moreover, the developers need to know what users need. In this case, someone who is missing a feature or has a great idea, should also let the team know about it. | ||
In both cases, the procedure is the same. There is a software called ''bug tracking system'', in Scribus' case this is [http://www.mantisbt.org/ Mantis]. A bug tracking system allows developers to keep track of, discuss and review bug reports and RFEs (requests for enhancements). If you want to help to improve Scribus or absolutely need a feature, you are advised to use it. | |||
{{Clear}} | |||
==How to create an account== | ==How to create an account== | ||
[[Image:Mantis signup.png|500px|thumb|right|Scribus Mantis Bugtracker [http://bugs.scribus.net/signup_page.php Signup Page]]] | |||
{{Warning|Due to spam abuse, it happens sometime that the signup page is disabled. In such a case, request an account on one of the Scribus mailing lists ('''scribus-dev''' preferably, though '''scribus-user''' should also do)}} | |||
First, visit the [http://bugs.scribus.net/signup_page.php signup page]. | <big> | ||
First, visit the [http://bugs.scribus.net/signup_page.php signup page]. | |||
# Enter a login name, your email address and the digits displayed. | |||
# Then click '''''Signup''''' and wait until your account has been confirmed and you received a password. | |||
You can change your personal preferences any time in the tab "My account", provided you are logged in. | |||
Please take the time to check the different options. They may or may not be useful for you. | |||
</big> | |||
{{clear}} | |||
==Before filing a bug== | ==Before filing a bug== | ||
If something doesn't work as expected or you think you have the idea of the century, please don't start firing up bug reports galore. Chances are good someone has already had the same problem, perhaps even the same great idea. Five steps are recommended to ensure your report won't be closed as "duplicate" or "no change required". | If something doesn't work as expected or you think you have the idea of the century, please don't start firing up bug reports galore. Chances are good someone has already had the same problem, perhaps even the same great idea. '''Here are Five steps are recommended to ensure your report won't be closed as "duplicate" or "no change required"'''. | ||
#Read the [http://docs.scribus.net/ documentation] and rummage this wiki. There are lots of informations in different languages available, and perhaps someone has already turned his own experiences into a wiki article. | #Read the [http://docs.scribus.net/ documentation] and rummage this wiki. There are lots of informations in different languages available, and perhaps someone has already turned his own experiences into a wiki article. | ||
#Try to really use Scribus and learn about its concepts. Compared to other DTP programs, Scribus is not so hard to learn, but it is still quite different from, say, a word processor. | #Try to really use Scribus and learn about its concepts. Compared to other DTP programs, Scribus is not so hard to learn, but it is still quite different from, say, a word processor. | ||
#Tell the [http:// | #Tell the [http://lists.scribus.info/mailman/listinfo/scribus mailing list] about your problem/idea. Things normally get sorted out quickly. Often enough, a supposed bug is just lack of experience. It is also recommended to [http://search.gmane.org/?query=searchedterm&group=gmane.comp.graphics.scribus search] the mailing list archives for keywords. | ||
#Ask questions on [irc:// | #Ask questions on [irc://libera.chat/#scribus IRC]. This is especially useful for "real time" support. | ||
#If your questions still haven't been answered, you should browse the bug database. You can search for keywords. As you can see on the screenshot below, you can enter a keyword in the "Search" field. Then click '''''Apply''''', and Mantis will search for all reports containing the string. '''If you don't know the correct English word''' to search for, you can skim the multilingual [[Glossary of technical terms used in Scribus and its translations|Glossary]] for a translation. If you use a '''non-English version of Scribus''' and want to look up the English names of menu items, just switch the Scribus interface to English: '''File > Preferences > General > Language''' | #If your questions still haven't been answered, you should browse the bug database. You can search for keywords. As you can see on the screenshot below, you can enter a keyword in the "Search" field. Then click '''''Apply''''', and Mantis will search for all reports containing the string. '''If you don't know the correct English word''' to search for, you can skim the multilingual [[Glossary of technical terms used in Scribus and its translations|Glossary]] for a translation. If you use a '''non-English version of Scribus''' and want to look up the English names of menu items, just switch the Scribus interface to English: '''File > Preferences > General > Language''' | ||
In case the bug has already been reported, there is no need to create a duplicate entry, but you can leave a comment that confirms the existing bug, or bring some more context or shed some light on the issue. | |||
[[Image:Mantis searching.png|center]] | |||
=== Ticket Status === | |||
<big>You will notice that the reports are colored differently. Here is the color legend:</big> | |||
<table class="width100" cellspacing="1"><tr><td class="small-caption" width="14%" bgcolor="#ffa0a0">new</td><td class="small-caption" width="14%" bgcolor="#ff50a8">feedback</td><td class="small-caption" width="14%" bgcolor="#ffd850">acknowledged</td><td class="small-caption" width="14%" bgcolor="#ffffb0">confirmed</td><td class="small-caption" width="14%" bgcolor="#c8c8ff">assigned</td><td class="small-caption" width="14%" bgcolor="#cceedd">resolved</td><td class="small-caption" width="14%" bgcolor="#e8e8e8">closed</td></tr></table><br /> | |||
{| | |||
|- | |||
|<span style="background-color:#ffa0a0">'''New'''</span> || The bug/RFE is reported, and no decision has been made as to how to handle it. | |||
|- | |||
| <span style="background-color:#ff50a8">'''Feedback'''<span> || Feedback is required from either the original reporter or someone who added a note to the report. This happens quite often in cases where an issue can't be reproduced. | |||
|- | |||
| <span style="background-color:#ffd850">'''Acknowledged'''</span> || Once the team has decided a suggestion is worth keeping in mind for further development, the status is changed to "acknowledged". This is mostly the case with RFEs. | |||
|- | |||
| <span style="background-color:#ffffb0">'''Confirmed'''</span> || If a reported bug could be reproduced by others, the status will change to "confirmed". This is what usually happens to bug reports. | |||
|- | |||
| <span style="background-color:#c8c8ff">'''Assigned'''</span> || A bug or RFE is assigned to a developer for fixing it or adding a feature. | |||
|- | |||
| <span style="background-color:#cceedd">'''Resolved'''</span> || A bug or RFE is resolved. That doesn't necessarily mean a developer wrote any code. If things can't or need not be fixed, the issue will be resolved as well. | |||
|- | |||
| <span style="background-color:#e8e8e8">'''Closed'''</span> || The end of a life span of a report. If all works well, the issue will finally be closed, and the scary number of reports/requests is a bit smaller. | |||
|} | |||
==How to file a bug report== | ==How to file a bug report== | ||
Lets suppose you have searched through the bugs database and found out that the bug had not yet been reported. Now, it will be useful to try to reproduce the bug, and to find out what is the simplest situation where it happens. This will help the developers to get a grip on the bug. You are then ready to file the bug report. | |||
[[Image:Mantis new report1.png|500px|right|thumb|Scribus MantisBT New Bug/Feature Report/Request form]] | |||
To file a bug report, you have to click on the '''''Report Issue''''' link in your browser. You will be presented a page with lots of fields for entries: | To file a bug report, you have to click on the '''''Report Issue''''' link in your browser. You will be presented a page with lots of fields for entries: | ||
[[ | *'''Categories''': Choose a category you think your report fits best. If you can't find an appropriate category, choose "General". | ||
*'''Reproducibility''': If you report a bug, can you reproduce it? How often does it happen? Choose the appropriate degree of frequency. RFEs have the reproducibility "Always", since the feature is always missing, until the issue is resolved. | |||
*'''Select Profile''': In your personal preferences you can create user profiles for your reports. This is especially useful if you use more than one OS. You create a profile for each operating system, and if you file a report on an issue that occurred on a particular system, you simply choose the profile instead of inserting the data (Platform, OS, OS Version) by hand all the time. | |||
*'''Platform''': Insert your CPU platform (e. g. x86, x86-64, PPC) | |||
*'''OS''': Your operating system (e. g. Linux, Windows, OS X) | |||
*'''OS Version''': e. g. Debian 3.1, SuSE 10.1, Win2000, OS X 10.3 | |||
*'''Product Version''': Scribus has many incarnations: the stable branch (1.4x), the developer branch (1.5). Make sure you choose the right one from the drop down menu. | |||
*'''Product Build''': This is especially important if you are using [[Building SVN versions with CMake|svn versions]] of Scribus. You find the relevant date in Scribus under '''Help > About Scribus'''. The date is of such importance, because the source code changes almost daily. An issue you report may very well already be resolved, in which case you will receive the recommendation to try current svn. '''Please don't report issues for old versions of Scribus.''' | |||
{{Clear}} | |||
[[Image:Mantis new report2.png|500px|left|thumb|Scribus MantisBT Bug Report form continued]] | |||
<big>If you have finished the preparations, you finally start writing: | |||
<!-- Space is intentional in the text below --> | |||
*'''Summary''': A short description of your report. This will become the "headline" in the bug tracker. | |||
*'''Description''': Describe your issue as precisely as possible, but keep it concise. '''No Novels here!''' It may also be helpful to upload some screenshots (see below). If you file a feature request, please add a real world scenario. The team needs examples to understand what the idea is and how this new feature would help people to work better and more efficiently. In other words, try to describe not only ''what'' and ''how'', but also ''why''. | |||
[[Image:Mantis new report3.png]] | |||
*'''Steps to reproduce''': If you are able to reproduce a bug, please write down the steps necessary for reproduction on other machines. | |||
*'''Additional information''': If you think other information, e. g. postings from the mailing list or messages [[how_to_debug_for_reporting|from a debugger]], are useful in this context, you can add them here. | |||
</big> | |||
{{Clear}} | |||
[[Image:Mantis new report3.png|500px|right|thumb|Scribus MantisBT Bug Report form attachment function]] | |||
You're almost done now, but you may want to upload a file, a screenshot for instance, or a Scribus sample file. | |||
Click '''''Search''''' or enter the path to the file on your hard drive or a URL. | |||
If you don't want a report to be seen by other reporters, but only the team, you can switch the status to "Private". This may be the case if you discover issues with an image that is protected by copyrights. Switch to "Private", and only a handful of people will see the file. | If you don't want a report to be seen by other reporters, but only the team, you can switch the status to "Private". This may be the case if you discover issues with an image that is protected by copyrights. Switch to "Private", and only a handful of people will see the file. | ||
Once everything is to your satisfaction, click '''''Submit Report'''''. Done! | Once everything is to your satisfaction, click '''''Submit Report'''''. Done! | ||
{{Clear}} | |||
==Enhanced Features== | ==Enhanced Features== | ||
| Line 73: | Line 113: | ||
Provided you are logged in, you can choose a more clearly laid out view of the bug tracker. Click the link '''''My view''''', and Mantis presents a structured view of recently changed issues: | Provided you are logged in, you can choose a more clearly laid out view of the bug tracker. Click the link '''''My view''''', and Mantis presents a structured view of recently changed issues: | ||
[[Image:Mantis my view.png]] | [[Image:Mantis my view.png|center]] | ||
<br /> | |||
<center><big> | |||
{| | |||
|- | |||
| '''Left column''' || || '''Right column''' | |||
|- | |||
| Unassigned reports || ||Your reports | |||
|- | |||
| Resolved reports || || All reports recently modified | |||
|- | |||
| Reports monitored by you || || | |||
|}</big></center> | |||
==Tips== | |||
== | ===Console Output=== | ||
Initiating Scribus using the Command Line Interface (CLI) will output useful data that one can add to the bug report. Find the directory Scribus is located in on your computer and enter the following on the CLI: | |||
<code>scribus --console --font-info</code> | |||
=== Adding a Backtrace === | |||
[[ | [[How to debug for reporting]] | ||
Latest revision as of 21:45, 14 March 2023
Introduction
Scribus MantisBT @ bugs.scribus.net
Software development is almost useless without testing, and that's true for Scribus as well, of course. Testing means using the software, especially development versions. For Scribus this is currently the version1.7.0 series, which will one day become Scribus version 1.(stable-version + 2) bugs, for example v1.4 becomes v1.6.
Bugs, when discovered, need to be reported to let the developers know that something's wrong or at least seems to be wrong, so the problem can be fixed, if necessary. Moreover, the developers need to know what users need. In this case, someone who is missing a feature or has a great idea, should also let the team know about it.
In both cases, the procedure is the same. There is a software called bug tracking system, in Scribus' case this is Mantis. A bug tracking system allows developers to keep track of, discuss and review bug reports and RFEs (requests for enhancements). If you want to help to improve Scribus or absolutely need a feature, you are advised to use it.
How to create an account
Scribus Mantis Bugtracker Signup Page
 Warning: | Due to spam abuse, it happens sometime that the signup page is disabled. In such a case, request an account on one of the Scribus mailing lists (scribus-dev preferably, though scribus-user should also do) |
First, visit the signup page.
- Enter a login name, your email address and the digits displayed.
- Then click Signup and wait until your account has been confirmed and you received a password.
You can change your personal preferences any time in the tab "My account", provided you are logged in.
Please take the time to check the different options. They may or may not be useful for you.
Before filing a bug
If something doesn't work as expected or you think you have the idea of the century, please don't start firing up bug reports galore. Chances are good someone has already had the same problem, perhaps even the same great idea. Here are Five steps are recommended to ensure your report won't be closed as "duplicate" or "no change required".
- Read the documentation and rummage this wiki. There are lots of informations in different languages available, and perhaps someone has already turned his own experiences into a wiki article.
- Try to really use Scribus and learn about its concepts. Compared to other DTP programs, Scribus is not so hard to learn, but it is still quite different from, say, a word processor.
- Tell the mailing list about your problem/idea. Things normally get sorted out quickly. Often enough, a supposed bug is just lack of experience. It is also recommended to search the mailing list archives for keywords.
- Ask questions on IRC. This is especially useful for "real time" support.
- If your questions still haven't been answered, you should browse the bug database. You can search for keywords. As you can see on the screenshot below, you can enter a keyword in the "Search" field. Then click Apply, and Mantis will search for all reports containing the string. If you don't know the correct English word to search for, you can skim the multilingual Glossary for a translation. If you use a non-English version of Scribus and want to look up the English names of menu items, just switch the Scribus interface to English: File > Preferences > General > Language
In case the bug has already been reported, there is no need to create a duplicate entry, but you can leave a comment that confirms the existing bug, or bring some more context or shed some light on the issue.
Ticket Status
You will notice that the reports are colored differently. Here is the color legend:
| new | feedback | acknowledged | confirmed | assigned | resolved | closed |
| New | The bug/RFE is reported, and no decision has been made as to how to handle it. |
| Feedback | Feedback is required from either the original reporter or someone who added a note to the report. This happens quite often in cases where an issue can't be reproduced. |
| Acknowledged | Once the team has decided a suggestion is worth keeping in mind for further development, the status is changed to "acknowledged". This is mostly the case with RFEs. |
| Confirmed | If a reported bug could be reproduced by others, the status will change to "confirmed". This is what usually happens to bug reports. |
| Assigned | A bug or RFE is assigned to a developer for fixing it or adding a feature. |
| Resolved | A bug or RFE is resolved. That doesn't necessarily mean a developer wrote any code. If things can't or need not be fixed, the issue will be resolved as well. |
| Closed | The end of a life span of a report. If all works well, the issue will finally be closed, and the scary number of reports/requests is a bit smaller. |
How to file a bug report
Lets suppose you have searched through the bugs database and found out that the bug had not yet been reported. Now, it will be useful to try to reproduce the bug, and to find out what is the simplest situation where it happens. This will help the developers to get a grip on the bug. You are then ready to file the bug report.
To file a bug report, you have to click on the Report Issue link in your browser. You will be presented a page with lots of fields for entries:
- Categories: Choose a category you think your report fits best. If you can't find an appropriate category, choose "General".
- Reproducibility: If you report a bug, can you reproduce it? How often does it happen? Choose the appropriate degree of frequency. RFEs have the reproducibility "Always", since the feature is always missing, until the issue is resolved.
- Select Profile: In your personal preferences you can create user profiles for your reports. This is especially useful if you use more than one OS. You create a profile for each operating system, and if you file a report on an issue that occurred on a particular system, you simply choose the profile instead of inserting the data (Platform, OS, OS Version) by hand all the time.
- Platform: Insert your CPU platform (e. g. x86, x86-64, PPC)
- OS: Your operating system (e. g. Linux, Windows, OS X)
- OS Version: e. g. Debian 3.1, SuSE 10.1, Win2000, OS X 10.3
- Product Version: Scribus has many incarnations: the stable branch (1.4x), the developer branch (1.5). Make sure you choose the right one from the drop down menu.
- Product Build: This is especially important if you are using svn versions of Scribus. You find the relevant date in Scribus under Help > About Scribus. The date is of such importance, because the source code changes almost daily. An issue you report may very well already be resolved, in which case you will receive the recommendation to try current svn. Please don't report issues for old versions of Scribus.
If you have finished the preparations, you finally start writing:
- Summary: A short description of your report. This will become the "headline" in the bug tracker.
- Description: Describe your issue as precisely as possible, but keep it concise. No Novels here! It may also be helpful to upload some screenshots (see below). If you file a feature request, please add a real world scenario. The team needs examples to understand what the idea is and how this new feature would help people to work better and more efficiently. In other words, try to describe not only what and how, but also why.
- Steps to reproduce: If you are able to reproduce a bug, please write down the steps necessary for reproduction on other machines.
- Additional information: If you think other information, e. g. postings from the mailing list or messages from a debugger, are useful in this context, you can add them here.
You're almost done now, but you may want to upload a file, a screenshot for instance, or a Scribus sample file.
Click Search or enter the path to the file on your hard drive or a URL.
If you don't want a report to be seen by other reporters, but only the team, you can switch the status to "Private". This may be the case if you discover issues with an image that is protected by copyrights. Switch to "Private", and only a handful of people will see the file.
Once everything is to your satisfaction, click Submit Report. Done!
Enhanced Features
Personalised View
Provided you are logged in, you can choose a more clearly laid out view of the bug tracker. Click the link My view, and Mantis presents a structured view of recently changed issues:
| Left column | Right column | |
| Unassigned reports | Your reports | |
| Resolved reports | All reports recently modified | |
| Reports monitored by you |
Tips
Console Output
Initiating Scribus using the Command Line Interface (CLI) will output useful data that one can add to the bug report. Find the directory Scribus is located in on your computer and enter the following on the CLI:
scribus --console --font-info