Jump to content

Jimer's Guide to Bug Reporting

Jimer_Lins

By Jimer_Lins
in New Player Help

 Share

Recommended Posts

Jimer_Lins

Jimer_Lins

Posted
Posted

Greetings, programs!

 

Many years ago (2004, to be exact), I was playing Star Wars: Galaxies. At the time I wrote a guide on how to create good bug reports- it was very well-received, even making it into the SWG documenation archive.

 

I think guidance on writing good bug reports is sitll relevant, so I pulled it out, dusted it off and updated it for TOR. I hope you find it useful, and I welcome any feedback you might have to help me improve it!

 

Jimer's Guide to Bug Reporting

 

This document describes how to file a good bug report, what a bug report should contain, and provides some examples of good and bad bug reports. For some people, reading this will result in a "Thank you, Captain Obvious!" moment. =) Many people already file good, solid bug reports. Many do not, and not because they're not capable, but because they just aren't aware of what a good bug report is and why. This guide attempts to address some of that.

 

BUG REPORTS

 

Bugs. We've all seen them, had them affect us in various ways. Some are funny, some are annoying, some are weird, and some are "game-breaking".

 

According to the Jargon File, a bug is defined as follows:

 

bug: n. An unwanted and unintended property of a program or piece of hardware, esp. one that causes it to malfunction. Antonym of feature. Examples: "There's a bug in the editor: it writes things out backwards." "The system crashed because of a hardware bug." "Fred is a winner, but he has a few bugs" (i.e., Fred is a good guy, but he has a few personality problems).

 

As a software developer, I've dealt with my share of bugs. I've created more than a few, and fixed more than I can possibly count. When users report bugs, developers often get frustrated because the user doesn't always realize what the developer needs in order to find and fix the bug, and so the bug report is incomplete or not useful. This means the bug probably won't get fixed or won't get fixed to the user's satisfaction.

 

Then the user is left wondering why the developer didn't fix the problem. After all, he reported it- why didn't it get fixed? Bugs are going to exist in any software; that's a given. The more complicated the software, the more bugs are going to be in it, in general. The biggest problem with diagnosing/fixing bugs is that quite often fixing one bug can create others- this is called the "law of unintended consequences" and is the bane of software developers.

 

In a game like TOR, there are going to be hundreds of developers. They also have a very large test team. Your bug reports go to some group inside BioWare; it is *highly* unlikely that they go straight to a given developer, who has a large list of things on his or her "to-do" list. What is more likely is that they go to a tester for checking and reproducing, then entered/updated in their internal bug-tracking system.

 

What does this mean and why am I explaining this? Because it means that when you file a bug report, you're not talking to the developer who wrote the code with the bug in it. You're talking to a tester, most likely, who knows as much about the actual code as you do- that is, not a thing. Testers aren't developers; it's important to communicate as much as possible about a given flaw in the system to them as is humanly possible so that they can find a way to reproduce the issue and get it sent on to the dev team for fixes.

 

THE BUG REPORT INTERFACE

 

In the game, if you run across a bug, you can start the bug report interface in one of two ways: Open the help interface and press the appopriate button, or the easy way: type "/bug" into the chat window.

 

The bug reporting window in TOR is very simple- there's a single box to enter your bug report in. Kind of hard to mess up. You'll want to fill it out with as much detail as you can and with the right information to help the developers find the issue and resolve it. You may find after submitting it that your issue has already been reported as the game will search existing known issues and ask you if your issue matches one already known. If it does, then your job is done. If not, submit that sucker.

 

GENERAL DO'S AND DON'T'S

 

DO:

 

 

  1. Be polite.
  2. Include as much information as you can about the bug and the circumstances surrounding it.
  3. Use the English language (except obviously for those playing in other countries with a different language) and type out all your words. If you need a spellchecker, use an offline editor like Notepad and paste the bug report into the bug interface.

 

 

DON'T:

 

  1. Be rude, inflammatory, or nasty.
  2. Demand that the problem be fixed.
  3. Threaten to quit the game (if you're doing that, you really should just quit now).
  4. Use "l33t" or shortened words- "4" instead of "for", "u" instead of "you", "ur" instead of "your"/"you're". Just. Don't. Do. This. Seriously.

 

 

THE COMPONENTS OF A GOOD BUG REPORT

 

Every system is different, and the requirements for reporting bugs on those systems will be different. Here's my assessment of what's needed for a good bug report in TOR; the five "W"s: Who, What, When, Where, and Why, along with Repro Steps (more on this later).

 

Who Are You?

 

Your character name is important. Even though you're filing this bug in-game, which means your character and account are attached to it, include your character name in the bug report. If you have multiple characters, be sure you mention the one that you encountered the bug on! Also, which server are you on? Include that as well.

 

What Happened?

 

Describe, in detail, the bug. "In detail" means IN DETAIL. Provide all the info you possibly can, even if you think it's not necessary or the developers already know. You would be amazed at how often it's a tiny, totally unrelated detail that actually provides the answer or a hint to the developer as to what the problem might be. In summary: More Information Is Good .

 

When Did it Happen?

 

Even if you're filing the bug report at the time or right after you ran across a bug, include the date and time, make it down to the minute if you can- and include your time zone, please! "Around 11 PM last night" is useless to someone reviewing the bug report two days later in a different time zone; they've probably got about a thousand more to get through, and I can promise you the ones that require additional work to figure out exactly when it happened are not going to get the attention. Time zone is important, because this game is played by people all over the world, and the developers probably don't live in your time zone. "12/29/2011 at 10:53 PM PST" is much, much more useful.

 

Remember also that quite often, the process of hunting down bugs means going through system logs, which on this game, are probably quite large. So if the best you can give the poor sod that's trying to figure out what happened is a 30-minute window, that's a lot of logs to go through. If you can narrow that down to a one or two-minute window (or even 5-10 minutes), you've just saved the person hunting the bug a lot of work.

 

Where Did it Happen?

 

Be as specific as possible, and include the planet and coordinates if you can/if it's applicable. You can find coordinates under your minimap on the lower right. If it's something that's happening on an entire planet, say so, but mention where you first encountered the problem if applicable. Remember- more detail cannot hurt, and just might be the thing that solves the puzzle. If it happened in space or on your ship, describe the mision or situation and give all the details you can of where it happened.

 

Don't say things like "Taris" without saying where on Taris (zone, location name- you can find these above your minimap on the lower right). Why make them figure this out?

 

Why Did it Happen?

 

This one's tricky- you may not always know exactly why a bug happened to you. But this is where you get to describe what you were doing or what was going on when the bug was found. But provide as much detail as you can- include what you were doing, what you had done recently, and any other details you can come up with- even what you were wearing, if you were buffed, what stims you had taken and what companion you had out. Remember, even seemingly unrelated details can be important when tracking down what caused the bug.

 

Repro Steps

 

This, to a developer, is arguably the most important part of a bug report. How do you make it happen? Unfortunately, we can't always reliably reproduce a bug. In other cases, we could reproduce it reliably but don't want to. Imagine a bug with modding items that causes the mod to vanish; I'm not going to throw away a bunch of nice mods just to prove I can make it happen more than once!

 

When you do know what is required to make the bug happen, verify (if possible) that you can reliably reproduce it, and then put the steps that are required, in order, in your bug report. Be sure to include any basic assumptions that may not be implied by the steps- if the bug occurs only when you're wearing a particular piece of clothing, for example, be sure to include that.

 

Don't be afraid to be pedantic here; making the steps as clear and concise as possible will help and can't hurt. Not every person that sees your bug report will be a developer, and not every developer that does see it will be familiar with every system in the game. Also, it is quite likely that internal testers receive the bug reports and need to validate them in some manner before they get to the dev team. That means that if you can make sure someone can repro your bug by simply following directions, your bug report gets handled sooner.

 

BUG REPORT TEMPLATE

 

Here's a basic layout for submitting bug reports. This isn't required or anything, but it does provide a nice framework for getting all the relevant bits in one place. If you're submitting a bug report and something isn't applicable, then just leave that part out. For example, a bug report about a word being misspelled on the Character Skills screen probably doesn't require as much detail as one that involves a complex combat or crafting bug.

 

---------------------------[Cut Here]-----------------------------------

Character Name: [Your character name here. This is NOT your login name]

Server: [Your Server name]

Summary: [A concise description, in one sentence, of the bug.]

Date/Time: [Date and time you last experienced the bug.]

Location: [Full coordinates, if possible]

Description: [include a detailed description of the bug, what causes it or seems to, and any other information you can think of that might be useful to someone trying to diagnose the bug]

Repro Steps: [step-by-step instructions, if possible, on how to make this bug occur. If you can't provide full repro steps, note this and provide whatever you can. Even small amounts of information can help.]

---------------------------[Cut Here]-----------------------------------

 

EXAMPLES

 

Here's an example of a good bug report. No, this isn't a real bug. I made it up. Don't Panic. This would be the

portion of the bug report I would place in the text box of the bug report interface.

 

I have included the text "[THIS IS A SAMPLE, NOT A REAL BUG.]" several times so that people searching for bugs don't think this is a real bug.

 

---------------------------[EXAMPLE]-----------------------------------

Character Name: Jimer

Server: Juyo

Summary: Crafting exactly 5 Harbinger's Vestments using Qyzen Fess causes the items not to be returned (this is an example, not a real bug.)

Date/Time: December 29, 2011 8:53 PM Pacific Time

Location: Tatooine, -3223 1293

 

Description: If I send Qyzen Fess on a mission to make Harbinger's Vestments and stack four more of the same crafting mission, Qyzen returns and says he finished, but the items are not given.

 

I have verified that this occurs with only this schema and Qyzen Fess and only if I stack exactly 5 missions. If I stack four or fewer it works fine. It does not seem to matter if the crafting materials are in my inventory or cargo hold.

 

Repro Steps: (assumes you can make Harbinger's Vestments and have Synthweaving at the appropriate level, plus have Qyzen Fess as a companion, and have the materials to make five Harbinger's Vestments)

 

1. Send Qyzen Fess on a mission to craft Harbinger's Vestments.

2. Before the first mission has returned, send Qyzen on the same mission four more times.

3. Observe that none of the items are returned once Qyzen has completed the mission. [THIS IS A SAMPLE, NOT A REAL BUG.]

---------------------------[EXAMPLE]-----------------------------------

 

This bug report provides all the necessary information for a tester or developer to diagnose the bug, or at the very least provides the info necessary for them to start digging.

 

What it does NOT do is take out the consequences of the bug (losing all the crafting materials and items you wanted) on the hapless tester or dev that gets to pull this bug out of the queue. There's no ranting, no demands to fix the problem right now, and no demands to return the items lost. Remember, bug reports are NOT CSR tickets. You won't get any customer support for a bug report and you won't get a bug filed when you put in a CSR ticket.

 

If the situation described above were real, I'd also have filed a help ticket about the situation. I might be able to get my materials back.

 

Here's an example of a bad bug report.

 

---------------------------[EXAMPLE]-----------------------------------

DAMMIT BIOWARE YOU Stink! I wuz makng armr fur my friend and none of the showed up!

 

FIX IT NOW! I WANT MY ARMOR! YOU SUCK!!!!!

 

If u dno't fix tihs n give me my armor, I'm gunna quit this stupid game!!!

---------------------------[EXAMPLE]-----------------------------------

 

I don't think a description of exactly why this is a bad bug report is required. However, I can *promise* you that the TOR team gets a lot of these. I also doubt that any bug report that even remotely resembles this one is going to be looked at. There's no relevant information, and frankly- if I was the one reading this bug report, I'd assume that the person who wrote it didn't have enough room in their inventory for the items and ignore it as "Not Repro".

 

Remember, you're dealing with human beings, and you may actually know some game systems better than the person who reads your bug report. That's NOT because they're incompetent or because you're an uber gamer gawd, it's because this game is huge and not everyone on a test/dev team will know every aspect of the game, any more than you do.

 

SUMMARY AND CONCLUSIONS

Basically, I hope that this guide gives people a good starting point for filing solid bug reports that the testers and dev team can work with. I'll be happy to incorporate any constructive feedback into revisions of this guide.

Link to comment
Share on other sites
  • 1 month later...
daemian

daemian

Posted
Posted (edited)

Good post.

 

In some feedback regarding bug reports I've sent in, Bioware has specifically asked for the following info:

 

•Screenshot

•Client (ie French/German/English)

•Server (ie Cosmic Turbine / Darth Malak)

•Planet/Area Name (Taris/ Nar Shaddaa)

•Coordinates (e.g. X: 23 Y: -175 Z: 200)

•Character Name / Account Handle (Camaron)

•Character Level / Class / Advanced class (Level 14, Sith Warrior, Juggernaut)

•Quest Name ( Gree: Hydro Supply)

•Active Companion (Vette)

Edited by daemian
Link to comment
Share on other sites
kaug

kaug

Posted
Posted

Great guide thank you.

Didn't know that you could copy and paste from notepad into the game bug reporting window that helps heaps because you can only have 1 windows at a time. Now I can gather the bug information and paste it straight in.

 

One question i have is that my bug report was just locked without any answer. I'm wondering if the bugs are being forwarded on or just locked as spam.

Link to comment
Share on other sites
Vexxation

Vexxation

Posted
Posted

I get a few locked and I just 'assume' that they are forwarding them on - there being really nothing they can tell me other than 'we are forwarding it'. I know some people prefer to be told this over and over though as opposed to no response at ll.

 

I do know that if you are reporting broekn gathering nodes they *DO* need to know exact locations - not just 'in the works on corsuscant' (for example) because I've been asked for better detail on those and was unabe to provide it (being on the next planet by then lol).

Link to comment
Share on other sites
Bleakmage

Bleakmage

Posted
Posted
I was looking for the way to report a bug and I found this. Thanks :D More than I asked for and I started scanning after awhile, but comprehensive. I don't exactly follow all of those rules when reporting a bug, as I figure they have some way of tracking things, but maybe I'm wrong. I'll put more info in like server ects, but I've only come across one broken flashpoint and a buggy Darth Jadus or whatever his name is when you're. . .don't want to put up any spoilers :D
Link to comment
Share on other sites
 Share
Go to topic listing
×
×
  • Create New...