How To Report Bugs

Cave Troll cannot be defeated with some weapons.

HUD displays incorrect amount of ammo.

Graphics in level 3 is broken.

Each of the above statements describes a potential bug in your game. However, none of them provide information required by programmers or designers to fix the issue. Those are, of course, a bit exaggerated examples. Nevertheless, I’ve seen way too many imprecise, incomplete and even incomprehensible bug reports, both as a QA specialist in the IT industry and as a developer and designer in the game industry.

In this post, I’d like to present a bug report template that is, in my opinion, clear, effective and sufficient. Here it is:

There are two important remarks before I move on. Firstly, reporting bugs is all about communicating all that’s required to fix a bug, and nothing more. The main purpose of the above template is to provide such information. However, note that not every bug report must include all points.

Secondly, using some sort of a bug tracking tool is more than advisable. In case of very small projects, Google Docs could be a sufficient solution, but for more complex projects you’re going to need a tool that enables you to categorize, prioritize and filter bugs. I personally recommend Mantis for small and medium projects (10-30 people) and JIRA for big projects (30+ people). Keeping reported issues in order should be considered the first step towards fixing them.

Title

The title should be short and descriptive. Graphics in level 3 is broken surely is short, but not really descriptive. Skyscrapers in level 3 don’t have materials applied sounds better, and in this particular case the title alone might provide enough information to fix the bug (unless not all skyscrapers are affected).

Category

Each bug’s occurrence can be narrowed down to a specific game project area: User Interface, Audio, Dialogues, AI, etc. Such a category should be included in the bug report, as it helps to filter out a specific type of issue and points to a person/team to which a given bug should be assigned.

Severity/Priority

Severity describes how “harmful” a bug is. Slightly displaced UI button is a Minor issue, while a crash that prevents a player from completing the main quest is a Blocker. 

Priority is in many cases directly proportional to Severity. Bug tracking tools usually have a separate drop-down menus for Severity (e.g. Minor, Major, Critical, Blocker) and Priority (e.g. Low, Normal, High, Urgent).

Steps To Reproduce

This is the most important part. Without a detailed step-by-step instruction on how to reproduce a bug the person responsible for fixing it won’t able to do it or will spend too much time and effort investigating how to reproduce the issue. Listed steps should be as detailed as needed (knowing what’s needed comes with experience) but also as simple as possible. I’ll give some examples later on.

Current Result

Basically, this should answer the question “What happens after I perform all steps listed in the previous part (Steps to Reproduce)?” Bear in mind that sometimes a single screenshot or error log says more than a hundred words (see Attachments part).

Expected Result

This one is not always required, but in some cases the report is incomplete without indicating what actually should happen in a correct scenario (if there was no bug).

Affected Version

If you found a bug in a specific build that has a version number or code, this code should be included in the report.

Reproducibility

This indicates whether a bug always occurs when Steps to Reproduce are performed or whether it’s not recurrent or in some way difficult to track. In a perfect situation, before reporting a bug we should always come up with such Steps to Reproduce that always result in the bug, but in some cases it will not be possible (for example bugs connected with low performance are sometimes difficult to reproduce).

Platform

Not always required, but sometimes necessary. Examples:

Attachments

Those could be:

OK, let’s see how the bug descriptions listed at the beginning could look like with the bug template applied.

Example 1: Cave Troll cannot be defeated with some weapons.

Title: Great Axe doesn’t do any damage to Cave Troll
Category: Gameplay
Severity/Priority: Critical/High
Steps to Reproduce: 

Current Result: Cave Troll receives no damage
Expected Result: <rather obvious, so can be omitted>
Affected Version: 0.3.1
Reproducibility: always
Platform: any
Attachments: N/A

Example 2: HUD displays incorrect amount of ammo.

Title: Too much ammo is added after reload
Category: UI/HUD
Severity/Priority: Major/High
Steps to Reproduce: 

Current Result: HUD displays 55 bullets loaded (amount before reload + clip size)
Expected Result: HUD should display 30 bullets loaded (amount before reload + 5 after the reload)
Affected Version: 0.3.1
Reproducibility: always
Platform: any
Attachments: screenshot with incorrect value marked on HUD

Example 3: Graphics in level 3 is broken.

Title: Skyscrapers in level 3 don’t have materials applied
Category: Environments
Severity/Priority: Minor/Normal
Steps to Reproduce: <can be omitted, as the title is descriptive enough>
Current Result: please see attached screenshot
Expected Result: <rather obvious, so can be omitted>
Affected Version: 0.5b
Reproducibility: always
Platform: PS4
Attachments: screenshot with Skyscrapers

Handling bugs in an organized and consistent manner is essential for game quality. Using a clear and unified bug report template will boost your communication and team performance and, in the end, help deliver a smooth game experience that the players expect.

Thank you for reading.