Bug tracking for game development: reports, severity and fixes
For QA testers, producers and programmers on game teams. You get a bug report template that works for games, a clear way to separate severity from priority, and the full workflow in Gameheim: from reporting a bug to checking that its fix is in the build you are testing.
Why game bug reports are hard to act on
A bug in a game rarely depends on one screen. It depends on the level, the save, the build, the platform, the input device and sometimes on what the player did ten minutes earlier. A report that says "the door does not open" leaves the programmer to guess all of that, and most of the time spent on such a bug goes into rebuilding the situation, not into fixing it.
Three other problems show up on almost every team that tracks bugs in general-purpose tools that were never built for game production:
- The bug and the work are in different places. The bug sits in one list, the task that fixes it sits on the board, and nobody updates the bug when the task is done. Bugs stay open long after the fix, or get closed while the fix is still in progress.
- Closed does not mean in the build. A programmer submits the fix in changelist 1840, but QA is testing a build made from changelist 1820. The bug reads "Resolved", the tester still sees it, and the bug gets reopened for the wrong reason.
- Nobody knows why it was done that way. A bug is often the side effect of a design choice. Without a link to that decision, the fix undoes it, and the problem comes back in another form.
What a good game QA bug report contains
Whatever tool you use, a report a programmer can act on without asking questions has the same parts. You can copy this template into your team guidelines:
Game QA bug report templateTitle: What goes wrong, where, in one line
(e.g. "Player falls through floor after loading save in Harbor level")
Severity: Crash / Blocker / Major / Minor / Cosmetic
System: The part of the game (combat, UI, save system, audio...)
Build: Build name or changelist the bug was seen in
Platform: PC, console, device model, input device if relevant
Symptom: What you see, and what you expected instead
Steps to reproduce:
1. Start from a clean state (new game, a named save, a specific map)
2. One action per step
3. The last step is the one where the bug appears
Frequency: Always, or 3 times out of 10
Evidence: Screenshot, short video, log file- One bug per report. Two problems in one report means one of them gets closed with the other.
- Steps start from a known state. "Load save Harbor_03" beats "play for a while".
- Say how often it happens. A bug that appears 1 time in 20 needs a different investigation than one that appears every time.
- Attach the evidence. A 10 second video often replaces a paragraph of description, and a log shows what the video cannot.
How Gameheim tracks bugs for game teams
In Gameheim, bugs live in the same project as your tasks, your version control and your design decisions. Each bug has a key such as OFT-BUG-11 (the project code, then BUG, then a number), and that key connects it to everything else.
- Fields shaped like the template above. Title, severity, systems, symptom, steps to reproduce, cause, fix, the files involved, the changelist, commit or build where the bug was seen, and attachments (screenshots, videos and logs).
- Fix tasks drive the bug. From a bug you create the task that fixes it, already linked. When every linked fix task is done, the bug closes by itself. If a task is reopened, a bug that was closed automatically reopens too.
- Changelists link themselves. When you submit from the P4 Workspace in Gameheim and the changelist description mentions
#OFT-BUG-11, the changelist is added to the bug. Linked tasks bring their changelists along. - Commits on Git projects. On a Git project the bug keeps the commits of its fix instead: paste the hash of each one in the Commits section of the bug.
- Is the fix in this build? When the fix is made of Perforce changelists, the bug panel compares the fix changelist with the builds you register, and tells you which builds contain the fix.
- Decisions next to the bug. A bug can be linked to the design decisions behind it, so whoever fixes it can read why things are the way they are. See the game design decision log.
- Crashes turn into bugs. Crash reports from Unreal Engine builds are grouped in the Crashes view, explained by AI from their callstack, and can be linked to a bug. See set up the Unreal Engine crash reporter.
- One place to discuss. Each bug has a thread for comments with @mentions, shown together with the history of every change to the bug.
The bug page works on a phone too, so a tester playing a build on a device can report a bug and attach a photo or video from the same device. See the Gameheim mobile app.
How to report and fix a bug in Gameheim
This is the full path of one bug: the setup a lead does once per project, then reporting, triage, the fix and the check on the build.
- You are a member of the project. The default Team Member (Default) role can already read and report bugs (Bugs:
readandwritein Roles & Permissions). - Bug settings, deleting bugs and deleting builds need Bugs:
manage. LEAD accounts have it. - Changelists link to bugs automatically only for submits made from the P4 Workspace in Gameheim, which needs the Gameheim agent.
Define the systems of your game
Open Bugs in the sidebar and click Settings. Under Systems, add the parts of your game a bug can belong to (for example Combat, UI, Save system, Audio) with Add system. Each system has a name and a color, and you can rename, reorder or delete it. Systems are shared by every bug of the project and by the design decisions.
On the same page, decide whether you want the «Awaiting verification» step. When it is on, a bug whose fix tasks are all done goes to Awaiting verification instead of Resolved, so that whoever found it checks the fix on a build.
Report the bug
Click New bug. Only the Title is required, and Severity starts at Major. Fill in what you know: Systems, Symptom, Steps to reproduce, Cause (if you already know it), Files (one path per line, depot path or project-relative) and Seen in changelist / build (on a Git project the field is Seen in commit / build and takes a commit hash of 7 characters or more). Then click Report bug.
Under Attachments, add screenshots, videos (mp4, webm) and logs (txt, log, json), up to 50 MB each. You can also paste a screenshot straight into the form. The date the bug was found is set to today unless you change it later.
Triage the bug
Click a bug to open its panel. Anyone who can write bugs can change Status and Severity, toggle systems and edit the text fields. Move the bug to Investigating while someone looks at it and to Cause found once the cause is known, and write the cause in the Cause field for the next person.
The To resolve view lists open bugs, most severe first. Bugs with no task yet show as not planned: that list is your triage queue. If the bug is already reported, set the status to Duplicate and pick the original under Which bug is the original?
Plan the fix as a task
In the Fix tasks section click Create task. The task form opens with the title already set to
Fix OFT-BUG-11: <bug title>. Pick the assignee, priority and milestone as for any other task, and save. If the bug was Open, it moves to Investigating. To attach a task that already exists, use Link existing task.On the Task Board, the task shows a fix of OFT-BUG-11 badge that opens the bug. The bug list shows who is working on it, taken from the assignees of its fix tasks. For planning the task itself, see game development task tracking.
Submit the fix with the bug key
When you submit from the P4 Workspace, mention the bug in the changelist description. The changelist appears in the bug under Changelists, marked named in submit.
Changelist descriptionFix floor collision after loading a save #OFT-BUG-11 done#OFT-BUG-11only links the changelist to the bug.#OFT-BUG-11 donealso closes the bug, but only if it has no open fix task. If fix tasks are still open, the bug closes when they are done.- Closing the fix task (from the board, or with its own key in the submit) closes the bug when it was the last open one.
On a Git project, link the fix by hand: open the bug, paste the hash of the fix commit under Commits and click Add commit. Both the full hash and the short form (7 characters or more) are accepted, and a fix can have several commits. A commit message that mentions the bug key does not link the commit or close the bug.
Check the fix on a build
On Perforce projects the Build section of the bug shows Fixed in changelist and, if your team registers builds with the Builds button on the bug page, the line Fix present in with the builds that contain it. For a build that is not registered, type its changelist under Does this build contain the fix? This comparison is valid for builds of the same stream.
On Git projects the Build section works the same way, with commits: it shows the commit and the build the bug was found in, and Fix present in lists the registered builds that contain every commit of the fix. Two commit hashes do not say which one came first, so Gameheim asks a Gameheim agent that has the repository cloned. The answer arrives a few seconds after you link the commit or register the build when such an agent is online, and the section says it is waiting until then.
If the «Awaiting verification» step is on, the reporter is notified when the bug reaches Awaiting verification. They test the build and move the bug to Resolved, or back to an open status if the problem is still there.
Bug statuses and workflow
Anyone who can write bugs can move a bug between any two statuses: there is no forced sequence. The Board view shows one column per status, and dragging a card changes the status.
| Status | Closed? | Use it when |
|---|---|---|
| Open | No | The bug is reported and nobody is on it yet. |
| Investigating | No | Someone is working out the cause. Creating a fix task moves an open bug here. |
| Cause found | No | The cause is known and written in the Cause field. |
| Awaiting verification | No | The fix is done and the reporter checks it on a build. Available only when the «Awaiting verification» step is on. |
| Resolved | Yes | The bug is fixed. |
| Cannot reproduce | Yes | Nobody can make it happen again with the information available. |
| Won't fix | Yes | The team chose to leave it, for example because it costs more than it is worth before launch. |
| Not a bug | Yes | The game works as designed. Linking the design decision explains why. |
| Duplicate | Yes | The same problem is already reported. Requires the original bug, which then lists its duplicates. |
Entering a closed status sets the Resolved on date. To plan a new fix for a closed bug, reopen it first: Create task is available only on bugs that are not closed.
Bug severity levels, and severity vs priority
Severity describes the impact of the bug on the game. Priority describes when the team will fix it. They are different questions: a typo in the main menu is cosmetic but may be urgent before a trailer, while a rare crash in a debug tool can be severe and still wait.
Gameheim keeps them apart. Severity is a field of the bug, set by whoever reports or triages it. Priority belongs to the fix task (Low, Medium, High, Critical), together with its milestone, assignee and due date, because that is where scheduling happens.
| Severity | A common way to use it |
|---|---|
| Crash | The game or the editor closes, hangs or asserts. |
| Blocker | The game keeps running but cannot continue: a progression stopper, a corrupted save, a build that cannot be tested. |
| Major | A feature is wrong or missing in a way players will notice, with a workaround or outside the main path. |
| Minor | A small functional problem that most players will not meet. |
| Cosmetic | Visual or text issues: clipping, a wrong texture, a typo, an alignment problem. |
The meanings above are a starting point, not rules enforced by Gameheim. Write your own in the project wiki so every tester uses the same scale (see game design document wiki).
Who sees a bug and who gets notified
A bug is visible to the members of its project who hold Bugs: read, and to LEAD accounts of the organization. Notifications go only to people who can read the bug at the moment it is sent: someone removed from the project, or without the permission, receives nothing.
| Event | Who is notified |
|---|---|
| A new bug is reported | Everyone on the project who can read bugs, except the reporter. |
| The bug is resolved or reaches Awaiting verification | The person who reported it. |
| A closed bug is reopened, or a fix task of a bug closed by hand is reopened | The reporter and the assignees of its fix tasks. |
| Someone comments | People @mentioned in the comment, plus the reporter, the fix task assignees and earlier commenters. |
| A bulk edit changes more than 5 of your bugs | One summary notification instead of one per bug. |
In Settings, Notifications, the New tasks preference also controls new bug notifications, and Task status changed controls the resolved, awaiting verification and reopened ones. Comment notifications are always delivered. For roles in general, see roles and permissions.
Saved views, bulk edit and CSV export
- Filters and sorting. Filter by status, severity, system, assignee (including Assigned to me and No tasks (not planned)) and by key or title. On Perforce projects you can also filter Resolved, not in a build yet.
- Views. Save a combination of filters, sorting and columns with Save view…. Tick Share with the project to make it visible to the team, and copy its link. Someone with Bugs:
managecan make a shared view the project default. Limits: 20 private views per person and 50 shared views per project. - Bulk edit. In the List view, select bugs with their checkboxes (up to 100 at a time) and change status or severity, add or remove a system, or delete them (delete needs Bugs:
manage). Bugs that cannot change are listed with the reason. Duplicate is not available in bulk, because each duplicate needs its own original. - Export CSV. Downloads the list as filtered and sorted on screen, with every summary column and a link to each bug. Choose the separator: Standard (,) or Excel Italian / European (;). The long texts (symptom, steps, cause, fix) are not included.
Troubleshooting
| What you see | Why, and what to do |
|---|---|
| The submit did not link the changelist to the bug | Only submits made from Gameheim are read. Check that the key has the right project code and the BUG part (#OFT-BUG-11, not #OFT-11, which is a task). The submitter also needs to be able to write bugs. |
#OFT-BUG-11 done did not close the bug | The bug still has open fix tasks. It closes when they are done. |
| Create task is missing | The bug is closed, or you cannot write bugs. Reopen the bug first. |
| Awaiting verification is not in the status list | The «Awaiting verification» step is off in the bug settings. |
| On a Git project Fix present in stays on waiting | The answer comes from a Gameheim agent that has the repository cloned through Gameheim. It arrives as soon as one of them is online and up to date. |
| The Build section says it cannot tell for some builds | The agent does not know one of the commits. Push the commit, or replace a short hash that matches more than one commit with the full one. Gameheim asks again by itself. |
| Add commit refuses what you typed | A commit is 7 to 40 hexadecimal characters. On a Git project the section takes commits, on a Perforce project changelist numbers. |
| File history says to connect the agent | The history of a file comes from your agent: start it, or install it. On Git projects it is read from your clone and needs agent 1.1.0 or later. |
| An attachment was refused | Only images, mp4 and webm videos, and txt, log and json files are accepted, up to 50 MB each and 20 per bug. |
Frequently asked questions
What should a game bug report include?
A one-line title that says what goes wrong and where, the severity, the system, the build or changelist, the platform, what you saw and what you expected, numbered steps to reproduce from a known state such as a named save, how often it happens, and evidence: a screenshot, a short video or a log. One bug per report keeps fixes and closures clean.
What is the difference between bug severity and priority?
Severity measures how badly the bug affects the game, from a crash to a cosmetic issue. Priority measures when the team will fix it, which also depends on deadlines, risk and who is available. In Gameheim severity is set on the bug, while priority, milestone and assignee live on the task that fixes it, where scheduling happens.
How do I link a Perforce changelist to a bug in Gameheim?
Mention the bug key in the changelist description when you submit from the P4 Workspace in Gameheim, for example #OFT-BUG-11. Add done to close the bug when it has no open fix tasks. You can also add a changelist number by hand in the Changelists section of the bug, and changelists of linked fix tasks are added automatically.
Does a bug close automatically when its fix is done?
Yes. When every fix task linked to a bug is done, the bug moves to Resolved, or to Awaiting verification if the project uses that step. If one of those tasks is reopened, the bug returns to its previous status. A bug closed by hand is never reopened automatically: the reporter and the fix task assignees get a notification instead.
Can QA testers report bugs from a phone?
Yes. The Bugs page works on phones and in the Gameheim mobile app. The New bug form accepts screenshots, mp4 and webm videos and log files up to 50 MB each, so a tester can record the problem on the device and attach it to the report straight away.
How do I find out if a build contains a bug fix?
On Perforce projects, open the bug and look at the Build section. It shows the changelist of the fix and lists the registered builds of the same stream that contain it. For a build that is not registered, type its changelist number and Gameheim answers yes or no. On Git projects this check is not computed.
How do I link a Git commit to a bug in Gameheim?
Open the bug on a Git project and paste the hash of the fix commit in the Commits section, then click Add commit. The full hash and the short form of 7 characters or more both work, and a fix can have several commits. Commits are linked by hand: a commit message that mentions the bug key does not link the commit.