|This is the second part of a tutorial outlining how to use the Second Life JIRA. It covers raising and submitting bug reports. For other lessons in this tutorial, please refer to the JIRA Tutorial Pages links, right.
If you have not filed a bug report before, then please read through all of the sections below.
If you have previously filed a bug report, and are looking to refresh your mind on specific points, please use the table of contents (right) to navigate to your specific topic of interest.
|Table of Contents
What Makes a Good Bug Report?
The primary use of the JIRA is to report issues and bugs within Second Life as they are identified by users. In this, a bug report should best be considered as a description of the issue encountered, together with an outline of what was expected when the issue was encountered. Ideally, a good bug report should:
- Focus on a single issue.
- Even if problems appear to be related, resist the urge to incorporate multiple issues on a single report, as this can confuse matters when trying to triage things.
- You can also raise multiple bug reports and cross-reference them. Linden Lab / those with authority to do so can then formally cross-link the reports as related issues.
- Be seen as a set of directions, providing:
- A clear set of steps outlining what you were doing when the problem occurred which should be written in a manner that allows someone else to follow them and (hopefully) encounter your problem, allowing them to understand it.
- A description of what you were expecting to happen when you encountered the problem.
- A description of what happened that differed from your expectation.
- Information on the viewer you were using, your location in Second Life at the time the problem was encountered, etc., all of which can easily be obtained from the viewer, as described in the instructions, below.
- Relevant supporting information, which may comprise: details of any error message which may have been displayed; a screen shot of the problem, if possible; the inclusion of relevant log files, if appropriate.
When Not to Raise a Bug Report
The JIRA should not be used to report problems which are specific to you or general enquiries (e.g. log-in issues; tier payments; running Second Life on a specific hardware configuration; land issues, etc). Please use the Second Life Support Portal and / or the forums to have these kinds of issue addressed.
As a broad rule-of-thumb, if the problem you’re encountered doesn’t require Linden Lab to make a change that can affect all users, then it probably isn’t appropriate to file a JIRA against it.
A Note to Users of Third-Party Viewers
Third-party viewer surface debug options and include their own capabilities which may not be visible / available in the official viewer. Because of this:
- If you encounter a problem you think affects most Second Life viewers, please check to see if it can be reproduced on the official SL viewer.
- If your preferred TPV has its own bug reporting mechanism, you can obviously report bugs through that using your preferred viewer. Check the site where you downloaded your third-party viewer to see if the developers offer a way to contact them with bug reports.
Before You File a Bug Report
It is possible the issue you are encountering is already known, or the subject of an existing JIRA. So before filing a bug report please consider checking the viewer’ release notes to see if the problem is listed as a Known Issue. You can do this in one of two ways:
- From within the viewer via HELP > ABOUT, and then clicking on the Release Notes link at the top of the panel.
- Via the Alternate Viewers wiki page for release candidate and project viewers.
It is also possible that the issue you’re experiencing may have already been reported – so try using the JIRA search capability to look for similar issues before submitting a bug report.
If you find that a bug report already exists for the issue, you can opt to click the WATCH option (top tight of a bug report, under PEOPLE) to receive updates to the JIRA via e-mail (you can uncheck WATCH should you no longer wish to receive these updates).
- If the COMMENT button is unavailable, you will need to request permission to make JIRA comments. Send an e-mail to letmein-at-lindenlab.com, giving your avatar name and reason for requesting access.
- Note that you do not need comment rights in order to file bug reports or feature requests.
Official SL Bug Report Information
- How to report a bug – Bea Linden, SL Knowledge Base.
- Bug Tracker – Second Life Wiki.
- Bug Tracker / Status – Second Life Wiki.
The Submission Form versus a Filed Report
A source of confusion for those not familiar with filing bug reports is that several of the fields used in the submission form do not match those seen in a filed report. This can make it hard to use an existing JIRA to try to understand exactly what information should be provided in the required fields of the submission form.
The table below is intended to help remove possible confusion, by providing the list of fields in the submission form on the left in the order in which they are encountered, and on the right, the equivalent fields in a filed bug report. The middle column describes what should appear in the fields.
Filing A Bug Report
- Log-in to the Second Life JIRA using your Second Life log-in credentials.
- Click on +Create Issue (top right).
- The Bug Report submission form will be displayed.
- Summary (required field): provide a concise summary of the issue – and remember that this will form the title of the bug report.
- If the bug is related to a specific Second Life project (e.g. Animesh), then include the project name, preferably in square braces (e.g. [Animesh] summary…”)
- What Just Happened? (required field: Provide a description of the actual behaviour you saw as a result of the bug.
- This information appears in the “Actual Behaviour” field of a filed in a report.
- What Were You Doing When It Happened? (required field: Give step-by-step instructions on how to reproduce the problem.
- If you received an error message relating to the issue, include it in this section, either as a quote, or as an annotated attachment if you were able to obtain a screen shot of the error message.
- If appropriate / applicable, use the Attachment Browse button at the bottom of the film to include images of the issue as you encountered it. Multiple images can be submitted, but ensure they are clearly labelled / annotated. Note individual files can be no larger than 10 Mb.
- Again, if appropriate, attach your viewer’s log files – see Log Files, below, for more.
- This information appears in the “Steps to Reproduce” field of a filed bug report.
- What were you expecting to happen instead? (required field): provide a description of what you were expecting to happen.
- If appropriate / applicable, use the Attachment Browse button to include images of what you were expecting to happen, again make sure they are clearly labelled / annotated.
- This information appears in the “Expected Behaviour” field of a filed bug report.
- Is there anything you’d like to add? (optional): use this section to provide any additional information you think may be of value in helping to assess the issue you have encountered.
- Do not feel obliged to complete this field if you have nothing further to add to the information supplied in the earlier fields.
- This information appears in the “Other Information” field of a filed bug report.
- Environment (required field): use this section to provide information on the environment – viewer and simulator – in which you encountered the problem. This information can be obtained directly from the viewer.
- If the issue you’ve encountered is simulator-related (e.g. script issues or similar), make sure you’re in the region where you encountered the problem.
- In the viewer, go to Help > About Second Life. This opens a floater with the Info tab selected. At the bottom of this panel is a Button: Copy to Clipboard. Click on this to copy the information displayed in the panel.
- This information includes: the version of the viewer you are using; your location in Second Life at the time the information was copied; the simulator version for the region you are on (hence the importance of being in the region where the problem occurred); core information about your computer: operating system / version; CPU, RAM, GPU and graphics driver, etc.
- Paste this information into the Environment field in the bug report.
- The remaining fields in the form are optional:
- Where: an additional field for entering the SLurl for the region where the issue was encountered (a Map link is also fine).
- System: two fields to help refine the nature of the issue. The first allows you to select the affected area of Second Life: viewer, simulator, SL website, Linden-made content in SL; the second offers a series of further options based on the first section.
- Security Level: a drop-down to select the security level to be assigned to the report> These are: Public – viewable to anyone access the Second Life JIRA; Triagers and Reporter: only viewable by those with specific JIRA access and the person raising the report.
- When you have confirmed the information is correct and as clear as possible, and any images / files are attached, click the Create button at the bottom right of the form to submit your bug report.
One of the most useful aids for helping to deal with bug reports are Second Life log files. These are:
- SecondLife.log: stores status and debugging output from the Viewer during the current logged-in session.
- This file grows while the viewer is active. If it gets too large, it is trimmed by the crash logging application.
- SecondLife.old: when the viewer re-starts, it renames the existing SecondLife.log to SecondLife.old. SecondLife.old is used when the Viewer reports a freeze in the previous execution.
- SL_Launcher.log: stores status and debugging output of the launch and update processes that start the viewer or update it. This file is appended to, not overwritten, but will be trimmed over time.
- SL_Launcher.old: back up copy of SL_launcher.log created from the prior launch.
- crash_table.lock: Tracks the process IDs of currently running Viewers, such that if one Viewer crashes, crash data is sent the next time the Viewer is run.
- SecondLife.start_marker: a marker file that should only live as long as the Viewer is running.
- dump-[UUID]: A folder that exists when the Viewer is either running or has crashed. It contains log files with information that does not need to be written immediately at the time of a crash, in order to lighten the load of the crash reporting tool and increase the likelihood of a successful crash report.
Note: the Second Life log files also include a file called crashreport.log. However, this can contain sensitive information, and should be manually reviewed before being sent to Linden Lab. If you are unsure about doing this, or in attaching the crashreport.log file, make a note of the time the crash occurred in one of the fields of the bug report form (e.g. in What Just Happened, for example).All of these log files are located in the logs folder where user data is stored.
- Windows log files location: C:\Users\[user data]\AppData\Roaming\SecondLife\logs.
- Mac OS log files location: /Users/<username>/Library/Application Support/SecondLife/logs.
These files can be attached to a bug report using the Attachment Browse button. You can ZIP / compress the log file folder prior to attaching if to the bug report.
What Happens Next?
Submitted bug reports are generally triaged (reviewed and assessed) within 24 hours of submission, Mondays through Fridays. This will result in one of three likely actions:
- It Needs More Information: if the report is deemed to vague, is not easy to understand, doesn’t contain sufficient instructions to reproduce a bug, etc., it may be re-opened for more information to be added. Reports in this state will be periodically checked by the Lab to see if sufficient information has been supplied.
- When providing additional information, reporters must click the Info Provided button. Failure to do so could result in the updating going unnoticed.
- It gets Accepted and cloned into the Lab’s internal JIRA system for tracking.
- It is Closed with no further action. The reason for it being closed may be given as one of the following:
- Contact Support: the issue does not belong in the Bug Tracker, and needs to be handled through the Support Portal or Second Life Answers.
- Expected Behaviour: the issue is not regarded as a bug, bug is seen as functioning as intended. See: Expected Behaviour aka Not a Bug (Second Life wiki).
- Duplicate: there’s another issue about the same problem.
- Unactionable: the described issue is not in a form that allows action to be taken (e.g. it is too broad).
- Not Applicable: the reporter has decided to close the issue.
When a Bug Report Is Accepted
Note that when a bug report is Accepted, it does not mean it will be acted upon immediately. There are a number of factors which may influence if / when it may be actioned, including:
- The severity of the issue reported.
- Current workflow, including work in progress which may help resolve a bug / issues related to a bug.
As such, a bug report can remain as Accepted for an extended period of time.