Reporting workflow

When reporting bugs or making suggestions, this workflow will help make sure that everyone follows the same convention. This will make it easier for everyone to see if an issue has already been been submitted, and make it easier for developers to recognize a given issue.

Please follow the checklist below when reporting a new issue.

New issue checklist

  1. Check if the bug or suggestion already exists by searching the tracker; filtering by Categories or Subject can speed this up. If the issue you want to report is already listed, you can comment on it if you have new information.
  2. If not in the tracker, make a new issue; select the appropriate option to describe it as a bug or suggestion. If it is a sensitive thing, you can mark it as "Private".
  3. Summarize the issue in the subject line. If it's an issue specific to a map then start the subject line with the map name like "02_NYC_BatteryPark:", followed by the issue summary. If it applies to multiple instances of the same location you can type "xx_NYC_BatteryPark" before the summary. Since multiple-instance maps are often clones of each other, any issues in one version might appear in others, and thus could be applicable to all of the instances. If you are unsure about this, just skip the map name portion of the subject line.
  4. Enter a description if needed to further explain the issue. Information about what "gameplay style" you are plaing (Game Options) is often helpful.
    For issues relating to particular locations in maps, it is helpful to include a small standard report by typing "report" in the console inside the game. That will dump some report info into your clipboard that you can paste into this description box. Also a screenshot is much appreciated (we prefer .jpg format).

For beta-testers

If you have "Reporting" privileges (given to our beta testers) you also can specify a Category. This will help with keeping things organized and in some cases automatically assigns a person to the issue.

Category

The different categories are as follows.
  • Audio/Music: relates to almost any sound and music content in the game.
  • Code: for global issues like bugs with weapons, scripted sequences not working, incorrect properties on items.
  • Conversation: Any issues with convo logic, speech, text and so on.
  • Geometry: for any issues relating to the world geometry like missing surfaces, invisible collision, "kill spots", or an architectural issue.
  • Mapping, non-geo: for any issues in the map that are not geometry related such as like pickups, NPCs, lighting or other properties on items in the maps. Properties on doors/hatches go here but any actual alteration to the appearance of it is geometry related.
  • Mesh: for any issue concerning a 3D model in the game. 3D models are non-geometry items you can see and interact with (computers, guns, chairs, etc). Doors are interactive, but belong under the geometry heading.
  • Misc: Any issue you don't find a category for.
  • Texture: Anything wrong with a texture image. Textures are the images placed onto geometry and models in the game world. An issue for this category could be a misspelled advertisement or other visual issue. Texture misalignments in maps go in mapping, non-geo issues instead.

For issue supervisors

If you have "Issue supervisor" privileges you also can specify Statuses, Priority, Assignee, Watchers and Parent Tasks.

Status

For Status you can pick between "New", "Incomplete" or "Triaged".
  • New is the default status for all issues and should be kept unless it fits into the two other statuses.
  • Incomplete is for bugs/suggestions that do not provide enough information to be implemented or fixed. Insufficient information when reporting an issue can lead to difficulty in reproducing and addressing a bug; in cases where that happens, issues will be given this status until more helpful information is provided.
  • Triaged is for when you've verified the bug yourself and you've made sure all needed information to verify the issue is in the description.
Developers have a few more statuses to choose from.
  • Won't fix indicates that a given bug or suggestion won't be fixed because it does not fit with the plans of the mod. A note should be left in addition to this status change to indicate why.
  • In-Progress should be picked when you have started working on something, usually a larger issue that might take some time to complete. For fast issues you usually just close them directly in the commit message.
  • Done, normally you don't set this status yourself but its set for you when you are committing a fix/implementation by in the commit message say "Fixing: #xx".

Priority

There are a few different priority classes you can assign to issues. Please choose these as objectively as you can.

  • Undecided: This is the default class, can also be used when the issue is under discussion.
  • Low: Used for unimportant issues like hard to spot bugs or things that doesn't seem to affect a lot of people.
  • Normal: Sort of between "Low" and "High". This and "Low" will probably be the most common priority classes.
  • High: For more severe issues that a lot of people complain about and that affect the Revision experience negatively for a lot of people.
  • Critical: will be used for severe showstopper bugs that occur often. For instance killer BSPs, Crash-To-Desktop (CTD) that can be reproduced and other severe issues that needs attention immediately.

Assignee

Typically, most categories will have a default assignee but for Code and Mapping, non-geo those tasks are split between people and thus they have no default. In such cases for for managing tasks its possible to manually set the assignee. Probably going to be more useful for the developer to simply assign themselves to a task then for the issue supervisor to hand out tasks, but still.

Watchers

Watchers are basically people who should be notified about the issue when it updates. Can be useful for keeping certain people in the loop about something if needed.

Parent task

Any issues that depend on a parent issue can be referenced here. Can be useful if one issue causes other issues and you want to create a relationship between the two.