StarCraft® II

How to Write a Good Bug Report

(Sticky)

Posts: 7,026
This guide was written by my good friend Kahzgul, of the WoW Bug Report Forums, and was ported over/maintained/edited by myself, with his consent.

I've seen many people posting bugs in this forum that are not clearly written, or - in some cases - even in understandable English. As a 12-year professional in the video game industry, specifically testing, I feel like an adequate authority to help everyone learn how to write a good bug. I have included a sample bug which I will reference from time to time throughout this guide. This sample bug is not real, and never actually happened to me. Please do not mistake this guide for an actual bug report.

Why should I bother learning how to write a good bug?
The reason for writing a good bug is simple: The faster that the Blizzard testers can understand and reproduce a bug, the faster that bug will get fixed.

How do I know that I've found a bug?
If you think you've found a bug at all, you should report it. In the worst case, you have actually found a bug, and in the best case, someone will point out that what your experiencing is intended functionality and will (hopefully) explain how to avoid the issue that you're experiencing. Often, bugs will go unreported because people aren't sure if it is "worth" reporting. The fact of the matter is that *every* bug is worth reporting. What just looks like a small graphic error may actually be a quest item underground or a hole in the map. You're making the game better by reporting issues that you've noticed. As a side note, custom user interfaces can cause a variety of issues with the game, so please try to verify that the bug occurs without any custom UI mods loaded.

Before you write the bug
Do a search of the bug report forum. Make sure that your bug is not already in the forum. If it is, feel free to add any additional information to the existing thread, by try to avoid "me too" posts unless specifically requested by the Blizzard staff. When searching, use keywords that describe the bug as accurately as possible. For example: "Missing item" is not nearly as clear as "Missing 2H Weapon" or even "Missing Weapon." Also, try several searches. If your Missing Weapon search returns nothing like your bug, try searching by your class "Shaman item" or "Shaman weapon" etc. Once you've done a few good searches and are satisfied that your bug is not in the forum, you should post a new issue. Keep in mind that this forum is for the reporting and tracking of in-game bugs, and is *not* any sort of means of fixing the bug or correcting the trouble you encountered. For issue resolution, please contact the customer service forum.

What should I title the bug?
A bug's title should be a clear, concise description of the issue. Something like "Shaman 2H weapon disappeared" is good. "OMG game brokezor" is not good. Think about what keywords someone might use to search for your bug, and try to include a few in your title. That way, anyone who browses through the forum will instantly know what your bug is, just from the title.

Sixen suggests starting your title with a tag to help identify what your post is about:
  • For Gameplay bugs, prefix the thread with [Bug].

  • For Forum bugs, prefix the thread with [Forum Bug].

  • For Guides/Notes/Information, prefix the thread with [Guide].


What elements go into a bug description?
A bug description contains several important parts: First is the bug description (What happened), second are the steps to reproduce the bug (How do you make the bug happen), and third is any supporting evidence (links to screenshots, etc.). Since this is just a forum, and not a professional bug reporting tool, I don't think that anyone truly expects full research into issues or screenshots, movies, etc. of them. However, the more information that you can provide, the better! It is also sometimes helpful to list the "who" and "where" of a bug as well: Which character(s) expereince the bug and where the bug occurred. Sometimes the "who" and "where" will be what kind of computer and operating system you have, and where in the real world you happen to be located. The "why" is what the developers will find out and fix.

(Continued)
Edited by Sixen on 7/28/2010 7:34 PM PDT
Reply Quote
Posts: 7,026
So what makes a good description?
A good bug description is like good reporting in a newspaper. It should be an unbiased declaration of facts. Try to keep your emotion at encountering a bug out of the report, and try to include all of the relevant details. Good: "After patch 2.0.1, the 2H weapon that my Shaman, Kahdrick, had equipped, disappeared. it is not in my inventory, bank, or on my character. The missing weapon was 'The Unstoppable Force'." Bad: "Where is my TUF?! I hate you! #&&^$@". For more complicated bugs, the description will be longer. Also, if you take the time to investigate the bug more thouroughly, you may find more information to include in the description: "I have also found that other 2H weapons that I equip will disappear if I respec my talents. It seems that this bug is actually related to the loss of the 2H Axe and 2H Mace skills when unlearning talent points. Since all talent points were refunded to all players when patch 2.0.1 went live, this seems to be related. Note that 2H staff weapons will not be lost when unlearning talents (2H staff is not a talent-trained skill). This bug also affects dual-wielded weapons in the off-hand."

What makes a good list of steps to reproduce?
A good list of steps should start from the last place that you know the bug did not occur, and then list every step after that. It is probably safe to assume that the tester who reads your bug has some familiarity with the game, but they may not know all of the acronyms, etc., so it is best to refrain from using abbreviations or acronyms when listing steps. Also, be very careful about how specific a given step should be. For example, if your bug occurs with any 2H weapon, you want to specify "Any 2H Weapon" and not "The Unstoppable Force". However, if it only occurs with The Unstoppable Force, be sure that you specify that, and do not say "a 2H weapon." The steps to reproduce may sometimes seem absurd "Have Blizzard patch the game servers to version 2.0.1 from any 1.x.x version" and will often seem redundant to the information in the description. Keep in mind that the goal is to make everything as clear as possible so that the tester can reproduce the bug in one try. Towards that end, don't worry about posting the same information twice or even three times in your bug - it helps!

Do I really need screenshots and other supporting information?
Probably not. However, any additional information that you can provide will help the devs to track down the problem and - hopefully - fix it. Graphic bugs should probably always have a screenshot. Crash bugs should have the dump file (if possible). Other, general functionality bugs may only be visible in movies. Don't go too crazy, however - this forum is to help the tester to reproduce the bug on his or her end - they will get whatever supporting information the developer needs to fix the issue. If your bug is concise without a need for screenshots or other info, don't worry about it. The Blizzard posters can always ask you for more information if they need it.

How do I know that Blizzard is reading my bug reports? It's been stated time and time again that Blizzard reads every post in this forum. Be patient :)

Why didn't Blizzard respond to my bug report? Only Blizzard knows why they chose not to respond to your post. However, many of the responses I have seen on this forum are requests for additional information. Given that, it is safe to assume that if there's no Blizzard response to your bug, then you wrote a Good Bug! Congratulations!

Blizzard just patched the game, but my bug wasn't fixed! Do I need to report it again?
You don't need to report the bug again, but it may be helpful to add to your original post that the bug was found in the new version of the game. Keep in mind, however, that it is practically impossible to fix every bug in a game with the amount of depth and scope that WoW has. There are also some bugs that are far more severe bugs than others (both in terms of gameplay impact and difficulty of fixing it). Quick fix bugs may get fixed even if they aren't a major impact on gameplay, and difficult fix bugs that have large impacts on gameplay will probably be fixed as well. There's really no way to know which bugs are going to be fixed and which aren't. Again, this forum is merely for the reporting and tracking of bugs, and is not a guarantee of any fixes for those issues.

(Continued)
Reply Quote
Posts: 7,026
Blizzard says they fixed my bug, but the effects of that bug still persist!:
Often times, a bug (such as disappearing weapons when unlearning talents) will be fixed, but the fix of that bug does not magically make your previously lost items come back. For issues like this, you need to contact Customer Service, please use the customer service forum. Thank you, however, for reporting the bug here, and making sure that future WoW players did not experience it!

Philosophy of the Public Beta
It's important to understand what public betas are for, why they exist, and what is expected of players who are invited into public betas.

First and foremost, your presence here and in the beta is already helping to test the game! Public betas provide valuable information on server stress levels, bandwidth, system requirements, play balance, and the like. From those of us who plan on playing the final version of the game, thank you for helping to make it more stable, fun, and glitch-free!

That being said, there is much more that can be done to help with the beta process, and this post is designed to help you fulfill your role as a public beta tester.

What is a Public Beta?
Public Betas are pre-release, non-final versions of a game or other piece of software that are extended - usually on an invite-only basis - to the general public in order to help the development team test aspects of the programming and infrastructure that the financial budgets of software companies simply can't adequately fund. In lay terms, it's really absurdly expensive to hire 2000 people on a temporary and sporadic basis, locate them around the world, make sure they have a wide selection of computer hardware and operating systems and... you get the idea.

What is a Public Beta Tester?
That's you! Public Beta Testers aren't like normal Beta Testers. This isn't your job, no one is paying you, and you don't have to go to a special office to do your work. Your compensation is that you get to see the game early, and you get to help make sure that the final release version of the game is absolutely bullet-proof. As far as most companies are concerned, Public Beta Testers are great because they also don't think like professional Beta Testers. You see, a professional tester usually has a checklist of areas to cover, weird combinations to look at, and general gameplay to check out - but they aren't looking for the things you're looking for. Players look for the easiest path to victory, the most challenge, the most fun, exploits of game mechanics, new more effective strategies, and things that "build 1 zergling and 11 hydralisks. Does this work? Now build 2 zerglings and 10 hydralisks. Does this work?" sorts of checklists simply don't cover. There's a reason some people Beta Test as a job, and that's because they get stuck with the work of testing. You get the fun of testing - so enjoy yourself!

Why doesn't the game work?
This is a Beta version of the game, and as such, it isn't finished yet. It's like buying a car with no frame and only two wheels. Sure, it's a car, but it isn't going top speed yet. You should fully expect to encounter bugs, some small, and some large. Maybe the marine is blue instead of red. That's a pretty small graphics bug. Or maybe launching the game causes your hard drive to melt. That's a pretty major bug. Possibly the game always exits after 1 hour and 45 minutes of play. That's the parental control feature. In any event, you should expect a few bumps in the road, and be proud of yourself when you find one - that's the whole point of this Beta and every one of those bugs that you find now is one fewer bug that will be in the final release version of the game.

Why should I report bugs?
As I just mentioned, every bug that you find now is one more that won't be in the final release version of the game. What if the game was released with a bug that made zerglings immortal? Soon everyone online would be playing zerg (or getting facerolled by them), and that wouldn't be any fun. This is an opportunity to make a game that you love truly great, and reporting every issue that you encounter is how you take full advantage of that opportunity.

What is a bug?
As far as you should be concerned, if you have to ask "was that a bug?" then it was a bug. Public Betas are as much about your play experience as they are about technical bugs in the code. Maybe there's a cutscene that has a weird edit in it. Report it. Maybe there's a unit that seems to do excessive damage for how easy it is to produce. Report it. Maybe you keep thinking that you see tiny pixels blink every now and then in the corner of the screen. Report it. Blizzard has always tried to make games that truly embrace what the fans want to see and do, and all of your feedback helps them.

(Continued)
Reply Quote
Posts: 7,026
Will they fix my bugs?
The short answer is yes, but this is a tricky question. Blizzard will always address the issues that each Public Beta Tester raises. That does not mean that they will always fix those issues to your liking. Some players will report that Archons do too much damage. After looking at that issue, Blizzard may scale down their damage, increase the defense or health of other units, or decide that Archons are just supposed to be that awesome. What's important is to know that you did your part by reporting the issue, and not to take any action by Blizzard personally. And keep this in mind, too - Blizzard is taking action. Players sometimes feel like nothing is being done, but behind the scenes there are many very hard working people mainlining caffeine to work 20+ hour days, 7 days a week to make sure that every issue gets a full investigation. Sometimes figuring out just what is wrong takes time. Sometimes the code that solves the problem takes time. And sometimes what a player sees as a bug the designers will see as a feature. Have patience, and in the end what will come of the sum of all of the issue reports from all of the Public Beta Testers is going to be a significantly superior game to what would otherwise have shipped.

How much information should I put in my bug report?
As much as you possibly can. There's really no such thing as too much information. Specifically, what's listed here:
http://forums.battle.net/thread.html?topicId=23279958145#8
and here:
http://forums.battle.net/thread.html?topicId=23279958145#9

Should I just report my bugs in-game, or just on the forums, or both?
Both is better if you have the time - the in-game report will reach devs faster and keep you in the game, while the forum report spreads information about the bug more publicly and allows your fellow Public Beta Testers to add their own experiences with a particular issue all in one place.

Why did you write this?
I plan on buying StarCraft 2 when it comes out, and I hate to buy buggy games. Please do me a favor and do a good job testing!

Many thanks to all of the Public Beta Testers, the Blizzard development team, and the forum lurkers like me! And of course to Sixen, for posting this on my behalf.

Cheers,
Kahzgul
Reply Quote
Posts: 7,026
Please note that these are EXAMPLES only and are not real bug reports.

------------

Description: In 1v1 matches, my Zerglings will not move. They will rotate to face enemies, and even attack enemies that walk right up to them, but they won't run from where they spawn at all. Issuing commands to them will make them turn and face the direction that I want them to go, but they won't move. This bug may occur in other matches, I haven't tried them yet.

Steps:
1) Play a 1v1 match as the Zerg.
2) Spawns some Zerglings.
3) Tell them to go to a destination. Note that they will all turn and face that destination, but won't move.
4) Tell them to attack a target. Note that they will turn and face that target, but again, they won't move.

Other notes:
- This may occur on other size 1v1 matches, I haven't checked.
- This may occur during campaign mode, I haven't played as the Zerg yet.
- Possibly related: When the computer is the Zerg, its units will move, but the Zerglings don't animate, they just float around.
- Possibly related: If I have my console open, it is constantly spammed with "file not found::zergling_ani.lua" whenever Zerglings (mine or the computer's) are spawned.

------------

Description: When a Shaman unlearns his or her talent points, any equipped 2H Axe or Mace will disappear. The item is not placed in the player's bags or bank - it simply vanishes. This was first noticed when patch 2.0.1 was released, as it refunded all player talent points. It seems that any Shaman who has previously speced Enhancement with the 2-Handed Axes and Maces talent, and had one of those types of weapons equipped at the time, lost that item during the patch. Having one of these weapons equipped and unlearning talents will reproduce the bug.

Upon further examination, off-hand weapons that are equipped by a dual-wielding shaman will be lost when that shaman unlearns his talents, which is probably a related issue. Off-hand shields are not lost.

Steps to reproduce the bug from patching:
1) You must be playing as a Shaman with at least 11 talent points (level 20), in a server version prior to 2.0.1.
2) Invest those talent points into the Enhancement tree, with the 11th point going into the 2-Handed Axes and Maces talent.
3) Equip either a 2-Handed mace or a 2-Handed Axe.
4) Have the servers update to version 2.0.1.
5) Note that the 2-Handed Mace or Axe is missing.

Steps to reproduce the bug from unlearning talents:
1) You must be playing as a Shaman with at least 11 talent points (level 20), in the current live game version (2.0.1 as of this post).
2) Invest those talent points into the Enhancement tree, with the 11th point going into the 2-Handed Axes and Maces talent.
3) Equip either a 2-Handed mace or a 2-Handed Axe.
4) Visit any class trainer capable of unlearning your talents.
5) Pay to unlearn your talents.
6) Note that the 2-Handed Mace or Axe is missing.

Steps to reproduce the bug from unlearning talents while Dual-Wielding:
1) You must be playing as a Shaman with at least 31 talent points (level 40), in the current live game version (2.0.1 as of this post).
2) Invest those talent points into the Enhancement tree, with the 31st point going into the Dual Wield talent.
3) Equip a weapon in each hand.
4) Visit any class trainer capable of unlearning your talents.
5) Pay to unlearn your talents.
6) Note that the off-hand weapon is missing.
Reply Quote
Posts: 7,026
Reserved.
Reply Quote
Posts: 7,026
Reserved.
Reply Quote
Posts: 30
I think it would be absolutely *awesome* if Blizzard opened up a bug reporting system (such as Bugzilla) the way open source projects have. Granted I can easily see the maintenance nightmare but at least bugs can be closed and linked to the related bug and people could simply reference a Bug ID as opposed to multiple new threads posting about the same thing and no real organization happening, little information as to the status of the bug, search, etc...
Reply Quote
Posts: 7,026
Definitely agreed. They have an addon in WoW called the Feedback tool. A tool of this fashion on the new battle.net would've been amazing.
Reply Quote
Posts: 228
Is a typo a bug? What about a (unintentional) grammatical error? If not, what about something that completely changes the meaning of what’s being said?
Reply Quote
Posts: 7,026
Yes, report typo's here as well.
Reply Quote
Posts: 3
Nice guide. Don't forget to make it apply to SC2 instead of WoW.
Reply Quote
Posts: 7,026
Yar, going to make some changes, etc. But for the most part, a lot of it is in regards to reporting bugs themselves, regardless of the game.
Reply Quote
Posts: 94
Hi Sixen, I'm from the SEA server and I would like to ask for the permission of yourself and Kahzgul to copy this over to the SEA forums. I will, of course, give you and Kahzgul credit for the guide.

Thanks,
Dart.
Reply Quote
MVP
Posts: 7,026
Hi Sixen, I'm from the SEA server and I would like to ask for the permission of yourself and Kahzgul to copy this over to the SEA forums. I will, of course, give you and Kahzgul credit for the guide.

Thanks,
Dart.

I actually held off on posting it since there were no Bug Report Forums at the time. I'll go ahead and put it up right now, I have an SEA account as well.

EDIT: Looks like the SEA forums are bugged right now? I'll put it up whenever they're working.
________________________________________________
The Chat Gem Lives!
http://www.Sixen.org
http://www.DiabloFans.com
http://www.SC2Mapster.com
http://www.SC2Replayed.com
Edited by Sixen on 9/29/2010 1:05 PM PDT
Reply Quote
Posts: 94
That would be great, thanks. The forums are working fine for me.
Reply Quote
MVP
Posts: 7,026
Whoops, totally forgot to go back and do it. Posting it up now.
http://sea.battle.net/sc2/en/forum/topic/73177397
________________________________________________
The Chat Gem Lives!
http://www.Sixen.org
http://www.DiabloFans.com
http://www.SC2Mapster.com
http://www.SC2Replayed.com
Reply Quote
Posts: 6
U should give us a email,then we can give you the bug's replay .U could see it.
Reply Quote
MVP
Posts: 7,026
If you'd like, you can upload replays to SC2Replayed.com and post the link here.
Reply Quote

Please report any Code of Conduct violations, including:

Threats of violence. We take these seriously and will alert the proper authorities.

Posts containing personal information about other players. This includes physical addresses, e-mail addresses, phone numbers, and inappropriate photos and/or videos.

Harassing or discriminatory language. This will not be tolerated.

Forums Code of Conduct

Report Post # written by

Reason
Explain (256 characters max)
Submit Cancel

Reported!

[Close]