Bugs
From OpenSimulator
(Difference between revisions)
m (Robot: Replacing 'OpenSim' to 'OpenSimulator', which is the precise name) |
|||
| (31 intermediate revisions by 10 users not shown) | |||
| Line 1: | Line 1: | ||
| − | + | {{Quicklinks}} | |
| − | + | ||
| − | = | + | = How do I report a Bug? = |
| − | + | ||
| − | == | + | == Reporting Bugs == |
| − | + | OpenSimulator is [http://en.wikipedia.org/wiki/Development_stage#Alpha alpha software], this means that there are frequent bugs in the codebase, and many features that still need implementing. You can help us find and fix these problems by [http://opensimulator.org/mantis reporting bugs] to us or submitting patches. | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | The [http://opensimulator.org/mantis mantis] tool is one of the main channels of communication between OpenSimulator users and OpenSimulator developers for purposes of reporting bugs. '''It is NOT a customer support tool''', because there is no official customer support within the opensim project beyond that provided by '''volunteers''' in the opensim IRC and mailing list. It is also not a feedback tool like a forum. Please use assorted forums for that kind of discussion or contribution. If you want to use the mantis tool, you have to be willing to learn how Mantis is to be properly used in the OpenSimulator project, which is very different from other organizations' reporting & tracking systems. | |
| − | + | ||
| − | + | This explains how to generate and file a Mantis Bug Report, which really helps the continuous development of OpenSimulator. | |
| − | + | If your main interest is to have your problem solved, or send informal feedback, rather than help the development of OpenSim, then mantis is the wrong tool for you. Try signing on to #opensim IRC for that kind of help, where you can talk to other OpenSimulator users, exchange user experiences and get personalized volunteer help. | |
| − | + | ||
| − | If | + | If, however, you are willing to invest time to investigate the problem you are experiencing, your effort will be greatly appreciated. You should look at mantis as half-way between '''your effort to solve the problem''' and the developers effort to do the same (and fix the problem). For everything else, there are several IRC channels, mailing lists, and assorted grid-specific forums. |
| − | + | When you encounter a problem, before filing a Mantis Report, ask yourself the following questions: | |
| − | + | ||
| + | * '''Are you the ONLY one experiencing this problem or are there other people experiencing it?''' The fastest way to find an answer to this question is to sign on to the #opensim IRC channel and exchange a few words with other OpenSimulator users there. Another way is to browse/search this Mantis tool for current known bugs/errors. If you're not the only one, then chances are it's a real issue. If you're the only one, chances are you're doing something wrong. The mantis tool is the wrong place to report configuration or technical support problems, you're better off using the IRC and signing on to #opensim. In any case, | ||
| + | ** Is there something broken in your setup? | ||
| + | ** Have you misconfigured something? | ||
| + | ** Look at the OpenSim.log file. Is there something informative in there that will help you understand what's going on with your setup? An exception perhaps? | ||
| + | |||
| + | * '''Can you reproduce the problem systematically?''' Take time to understand the steps that lead to the problem. The more reproducible and better understood the problem is, the higher the chances are that it will get fixed. If you can't reproduce it, there is very little chance that the issue will be fixed. But reproducibility to ''you'' is not enough. Read on. | ||
| + | |||
| + | * '''Can you describe the problem to developers so that ''they'' can reproduce it without being you?''' | ||
| + | ** The best way to do this is to try to reproduce the problem in a standalone setup. This eliminates all the extra noise that adds fuzzyness to the issue. So try it in standalone first. If you are able to reproduce it like that, the chances of the problem being fixed soon increase dramatically. If the problem is related to the Hypergrid and distributed setups, try to reproduce the problem in only one machine with 2 opensim instances. From a developer's perspective, it will be easy to take your good description, reproduce it on their own standalones, and then fix it. | ||
| + | ** If you can't reproduce it in standalone mode, try to reproduce it in grid mode using the simplest possible grid -- something that a developer can also set up on one machine without much work. | ||
| + | ** If you can't reproduce it that way, and the problem only occurs within your special grid environment, chances are there's something wrong with your configuration or your special setup. Furthermore, the chances of a developer being able to fix the problem soon decreases dramatically. More than likely you will need to find volunteer technical support, or you may try to hire someone for a fee in order for him/her to take their time to investigate the issue with your grid. | ||
| + | |||
| + | === Bug Description === | ||
| + | |||
| + | Once you understand how to reproduce the problem, describe it on Mantis, along with a step-by-step recipe for a developer to reproduce it. In an ideal bug report, the description should be something like this: | ||
| + | |||
| + | Setup (standalone/grid/...), as detailed as possible | ||
| + | |||
| + | 1) Do A | ||
| + | |||
| + | 2) Do B | ||
| + | |||
| + | 3) Do C | ||
| + | |||
| + | ... | ||
| + | |||
| + | ==> Bang! problem | ||
| + | |||
| + | In every step, be as specific as possible, leaving no room for interpretation. For example, saying | ||
| + | |||
| + | "x) crashed the client by pulling up the task bar and killing the SecondLife process" is MUCH better than | ||
| + | |||
| + | "x) crashed the client"; | ||
| + | |||
| + | and | ||
| + | |||
| + | "y) create a new region by using a command like this on the console: create region ..." is MUCH better than | ||
| + | |||
| + | "y) create a region". | ||
| + | |||
| + | Remember, the purpose of your description is to help a developer experience the steps that lead to the problem, so that he/she can then fix it. | ||
| + | |||
| + | === When not to file a bug report === | ||
| + | |||
| + | Simply reporting a problem that you are experiencing is ok but it's completely ineffective for purposes of troubleshooting or problem solving. Mantis should not be used for that. Instead, report generic and/or non-reproducible and/or special setup problems informally in #opensim and/or #opensim-dev. Here are two examples: | ||
| + | |||
| + | - "TPs seem to be broken in OSGrid with r1234": report that in osgrid-related forums and #opensim | ||
| + | |||
| + | - "TPs seem to be broken altogether with r1234, and lots of ppl are seeing this too": let the developers know about it in #opensim-dev, maybe. They probably already know. | ||
| + | |||
| + | If all you can say about an issue is it's brief description or "This is happening to me, please help" or "Here's my informal feedback", Mantis is the wrong tool for it. Don't file a bug report, it will be closed promptly. | ||
| + | |||
| + | Please review the Mantis procedures/states etc.. on [[Bugs]] | ||
| + | |||
| + | '''Also, please do not propose features in Mantis, unless you also have accompanying code to implement said feature'''. The correct place to propose features is the opensim-dev mailing list in the first instance, and then the [[Feature Proposals]] wiki page. | ||
| + | |||
| + | == Steps for reporting a bug == | ||
| + | * Visit [http://www.opensimulator.org/mantis opensimulator.org/mantis] and search to see if your bug already exists in the system. If it does, please add a note with any additional comments or technical assistance such as steps to reproduce, symptoms, etc. | ||
| + | * A good bug report has the following properties: | ||
| + | ** Concise and to the point, IE: "Duplicating a primitive while sitting on it, crashes the region.". | ||
| + | ** Contains as much debug information as possible, if OpenSimulator threw an error before crashing it, a copy of this error is helpful. If not, pasting the last 50 lines from your opensim.log when appropriate is also potentially helpful. | ||
| + | ** If you can reproduce the bug, steps to reproducing it is a must. | ||
| + | ** Please do not submit bugs such as "OpenSimulator eats a lot of CPU time" without including information about your setup, and anything you or we may have done to trigger this, unfortunately we are not psychic and cannot guess what may have happened. | ||
| + | * Create an account on the opensim Mantis website, and hit 'Report new issue'. Please note that some free email providers may take a while for the confirmation email to appear. | ||
| − | |||
| − | + | == Bug States in Mantis == | |
| + | One of the goals is to get as many issues out of the new state as possible and get turned into good bugs that can be acted upon. Below is a lightweight state diagram that should help in deciding what state is appropriate for bugs in Mantis. | ||
| − | + | [[File:BugStates.png]] | |
| − | + | Some comments on states: | |
| + | * Bugs don't have to flow through all states to land somewhere. For instance, if a bug starts with a well written up description, and the person triaging the bug has seen the same issue, it can be moved straight to confirmed. As with everything, these are rough guidelines, use your judgement. | ||
| + | * A bug will be marked '''Resolved''' if the person working the bug believes it is fixed even if there isn't final confirmation from the reporter. If the reporter finds that it is not fixed, please just reopen the bug and add comments accordingly. | ||
| + | * Please leave closing of bugs to core team. A closed bug means we think it's gone forever, or the bug report is invalid. | ||
| + | * A bug in resolved or closed state can also be reopened if the bug still exists. Please read the bug report and the attached notes carefully before doing this. | ||
| − | |||
| − | + | == Tips for Bug Descriptions == | |
| − | + | If the issue you're reporting is something causes crash or exceptions, it might be helpful to attach stacktrace or log shown in console to your report. If the bug is reproducible and you're using OpenSimulator source distribution on Mono, run Mono with debug option: | |
| + | <pre> | ||
| + | mono --debug OpenSim.exe | ||
| + | </pre> | ||
| + | It will add source file names and line numbers to your stacktrace, which enables developers easily find the erroneous steps. | ||
| − | |||
| − | + | = See Also = | |
| − | + | * [http://en.wikipedia.org/wiki/Development_stage#Alpha Alpha Software] | |
| + | * [http://www.opensimulator.org/mantis Report a Bug using Mantis] | ||
| − | + | [[Category:Users]] | |
| + | [[Category:Support]] | ||
| + | [[Category:Help]] | ||
| + | [[Category:Configuration]] | ||
| + | [[Category:Getting Started]] | ||
| + | [[Category:Development]] | ||
Latest revision as of 22:16, 3 March 2012
Contents |
[edit] How do I report a Bug?
[edit] Reporting Bugs
OpenSimulator is alpha software, this means that there are frequent bugs in the codebase, and many features that still need implementing. You can help us find and fix these problems by reporting bugs to us or submitting patches.
The mantis tool is one of the main channels of communication between OpenSimulator users and OpenSimulator developers for purposes of reporting bugs. It is NOT a customer support tool, because there is no official customer support within the opensim project beyond that provided by volunteers in the opensim IRC and mailing list. It is also not a feedback tool like a forum. Please use assorted forums for that kind of discussion or contribution. If you want to use the mantis tool, you have to be willing to learn how Mantis is to be properly used in the OpenSimulator project, which is very different from other organizations' reporting & tracking systems.
This explains how to generate and file a Mantis Bug Report, which really helps the continuous development of OpenSimulator.
If your main interest is to have your problem solved, or send informal feedback, rather than help the development of OpenSim, then mantis is the wrong tool for you. Try signing on to #opensim IRC for that kind of help, where you can talk to other OpenSimulator users, exchange user experiences and get personalized volunteer help.
If, however, you are willing to invest time to investigate the problem you are experiencing, your effort will be greatly appreciated. You should look at mantis as half-way between your effort to solve the problem and the developers effort to do the same (and fix the problem). For everything else, there are several IRC channels, mailing lists, and assorted grid-specific forums.
When you encounter a problem, before filing a Mantis Report, ask yourself the following questions:
- Are you the ONLY one experiencing this problem or are there other people experiencing it? The fastest way to find an answer to this question is to sign on to the #opensim IRC channel and exchange a few words with other OpenSimulator users there. Another way is to browse/search this Mantis tool for current known bugs/errors. If you're not the only one, then chances are it's a real issue. If you're the only one, chances are you're doing something wrong. The mantis tool is the wrong place to report configuration or technical support problems, you're better off using the IRC and signing on to #opensim. In any case,
- Is there something broken in your setup?
- Have you misconfigured something?
- Look at the OpenSim.log file. Is there something informative in there that will help you understand what's going on with your setup? An exception perhaps?
- Can you reproduce the problem systematically? Take time to understand the steps that lead to the problem. The more reproducible and better understood the problem is, the higher the chances are that it will get fixed. If you can't reproduce it, there is very little chance that the issue will be fixed. But reproducibility to you is not enough. Read on.
- Can you describe the problem to developers so that they can reproduce it without being you?
- The best way to do this is to try to reproduce the problem in a standalone setup. This eliminates all the extra noise that adds fuzzyness to the issue. So try it in standalone first. If you are able to reproduce it like that, the chances of the problem being fixed soon increase dramatically. If the problem is related to the Hypergrid and distributed setups, try to reproduce the problem in only one machine with 2 opensim instances. From a developer's perspective, it will be easy to take your good description, reproduce it on their own standalones, and then fix it.
- If you can't reproduce it in standalone mode, try to reproduce it in grid mode using the simplest possible grid -- something that a developer can also set up on one machine without much work.
- If you can't reproduce it that way, and the problem only occurs within your special grid environment, chances are there's something wrong with your configuration or your special setup. Furthermore, the chances of a developer being able to fix the problem soon decreases dramatically. More than likely you will need to find volunteer technical support, or you may try to hire someone for a fee in order for him/her to take their time to investigate the issue with your grid.
[edit] Bug Description
Once you understand how to reproduce the problem, describe it on Mantis, along with a step-by-step recipe for a developer to reproduce it. In an ideal bug report, the description should be something like this:
Setup (standalone/grid/...), as detailed as possible
1) Do A
2) Do B
3) Do C
...
==> Bang! problem
In every step, be as specific as possible, leaving no room for interpretation. For example, saying
"x) crashed the client by pulling up the task bar and killing the SecondLife process" is MUCH better than
"x) crashed the client";
and
"y) create a new region by using a command like this on the console: create region ..." is MUCH better than
"y) create a region".
Remember, the purpose of your description is to help a developer experience the steps that lead to the problem, so that he/she can then fix it.
[edit] When not to file a bug report
Simply reporting a problem that you are experiencing is ok but it's completely ineffective for purposes of troubleshooting or problem solving. Mantis should not be used for that. Instead, report generic and/or non-reproducible and/or special setup problems informally in #opensim and/or #opensim-dev. Here are two examples:
- "TPs seem to be broken in OSGrid with r1234": report that in osgrid-related forums and #opensim
- "TPs seem to be broken altogether with r1234, and lots of ppl are seeing this too": let the developers know about it in #opensim-dev, maybe. They probably already know.
If all you can say about an issue is it's brief description or "This is happening to me, please help" or "Here's my informal feedback", Mantis is the wrong tool for it. Don't file a bug report, it will be closed promptly.
Please review the Mantis procedures/states etc.. on Bugs
Also, please do not propose features in Mantis, unless you also have accompanying code to implement said feature. The correct place to propose features is the opensim-dev mailing list in the first instance, and then the Feature Proposals wiki page.
[edit] Steps for reporting a bug
- Visit opensimulator.org/mantis and search to see if your bug already exists in the system. If it does, please add a note with any additional comments or technical assistance such as steps to reproduce, symptoms, etc.
- A good bug report has the following properties:
- Concise and to the point, IE: "Duplicating a primitive while sitting on it, crashes the region.".
- Contains as much debug information as possible, if OpenSimulator threw an error before crashing it, a copy of this error is helpful. If not, pasting the last 50 lines from your opensim.log when appropriate is also potentially helpful.
- If you can reproduce the bug, steps to reproducing it is a must.
- Please do not submit bugs such as "OpenSimulator eats a lot of CPU time" without including information about your setup, and anything you or we may have done to trigger this, unfortunately we are not psychic and cannot guess what may have happened.
- Create an account on the opensim Mantis website, and hit 'Report new issue'. Please note that some free email providers may take a while for the confirmation email to appear.
[edit] Bug States in Mantis
One of the goals is to get as many issues out of the new state as possible and get turned into good bugs that can be acted upon. Below is a lightweight state diagram that should help in deciding what state is appropriate for bugs in Mantis.
Some comments on states:
- Bugs don't have to flow through all states to land somewhere. For instance, if a bug starts with a well written up description, and the person triaging the bug has seen the same issue, it can be moved straight to confirmed. As with everything, these are rough guidelines, use your judgement.
- A bug will be marked Resolved if the person working the bug believes it is fixed even if there isn't final confirmation from the reporter. If the reporter finds that it is not fixed, please just reopen the bug and add comments accordingly.
- Please leave closing of bugs to core team. A closed bug means we think it's gone forever, or the bug report is invalid.
- A bug in resolved or closed state can also be reopened if the bug still exists. Please read the bug report and the attached notes carefully before doing this.
[edit] Tips for Bug Descriptions
If the issue you're reporting is something causes crash or exceptions, it might be helpful to attach stacktrace or log shown in console to your report. If the bug is reproducible and you're using OpenSimulator source distribution on Mono, run Mono with debug option:
mono --debug OpenSim.exe
It will add source file names and line numbers to your stacktrace, which enables developers easily find the erroneous steps.
