|This is the second part of a tutorial outlining how to use the Second Life Jira. It covers raising bug reports. For other lessons in this tutorial, please refer to the Jira Tutorial Pages links, right.
If you have not raised a bug report before, then please read through all of the sections below.
|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 file 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 File 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.
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 you file a new bug report please consider:
- Checking the viewer release notes to see if the bug is listed as a Known issue. This can be done in one of two ways:
- From within the viewer you’re using via HELP > ABOUT, and then clicking on the Release Notes link at the top of the panel.
- By checking the Alternate Viewers wiki page to see if the issue has been noted in their release notes.
- Using the Jira Search option to see if the issue has already been reported.
If you find that a bug report already exists for the issue, you can opt to click the WATCH option (top right of a bug report, under People) to receive e-mail updates on the Jira (you can also uncheck WATCH at any time to stop receiving 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.
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 you can reproduce the bug on the official viewer, please file a bug report using / referencing the official viewer, not your preferred TPV.
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.
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.
Raising A Bug Report
- Log-in to the Second Life JIRA using your Second Life log-in credentials.
- Click on the blue Create button in the top menu bar.
- The Bug Report submission form will be displayed. Complete it as per the notes below.
- 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.
- 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 form 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.
- 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 at the bottom of the form to include images of what you were expecting to happen, again make sure they are clearly labelled / annotated.
- 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.
- 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.
- Attachment: use this option to add any suitable attachments to the report, in line with the notes above.
- Security Level: a drop-down to select the security level to be assigned to the report. These are: Public – viewable to anyone logged-in to 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.
The panel below provides an illustrated summary of the bug report fields as a quick reference, if preferred – click to view full size in a separate browser tab.
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.
- SecondLife.start_marker: a marker file that should only live as long as the Viewer is running.
All of these log files are located in the logs folder where user data is stored, as indicated below. This files can be be compressed / ZIPped into a single file prior to attaching to the bug report via the Attachment Browse button.
- Windows log files location: C:\Users\[user name]\AppData\Roaming\SecondLife\logs.
- Mac OS log files location: /Users/<username>/Library/Application Support/SecondLife/logs.
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 too 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.
- This will cause the Needs More Info flag to be displayed.
- 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 any update being missed.
- 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.