About This Document

This document, originally by UnderFlow, is licensed under the GNU General Public License.

Why Does Forge Use an Issue Tracker?

In the past, we used the forums to report bugs and features, but this had a couple of bad side effects. First, some of the topics grew quite large. Second, sometimes an issue would not get the attention of a developer, and would not be addressed.

The issue tracker, Mantis, provides a clean way to comment on issues as they evolve, it reduces the number of duplicated issue reports, and it greatly enhances the visibility of both old and new issues to the Forge developers.

Tutorial

What Kind of Issue Is It?

There are three major kinds of issues that the Forge developers want to keep track of. The first two are considered bugs, while the third is considered a feature. The general term for any of the three is "issue".

A Stack Report

If, during the course of using Forge, you encounter a window titled "Error" containing plain text starting with "An error has occurred. You can copy/paste this message or save it to a file", we call this a "Stack Report". These are sometimes called by other names: "crashes", "crash reports", "stack traces", or simply "an error has occurred."

Unexpected Behavior

If you did not get a Stack Report, but you have experienced a problem in how you think the game should work, we call this "Unexpected Behavior". This includes cases where the Computer opponent makes a bad, silly, or downright ridiculous decision in its efforts to thwart you. Before reporting Unexpected Behavior, please read the cards carefully to make sure you understand how they work. You may be surprised to find that Forge is actually enforcing the rules correctly.

Feature Request

If nothing incorrect is going on, but you want Forge to behave in additional or useful ways, we call it a "Feature Request".

Where Do I Report the Issue?

If your issue is from a release of Forge prior to the latest Beta, please upgrade Forge and try reproducing the issue before reporting it.

If you are reporting a Stack Report or Unexpected Behavior from the latest Beta release of Forge, you may post the issue to the same topic in which the Beta version was announced, instead of using Mantis directly. You can find this topic in the Forge Forum. If you don't get a timely response, then you may wish to search and report the issue in Mantis as described below.

If you are making a Feature Request, or if you are using any other version of forge, such as an "alpha", "git", "leading edge", or "nightly build" version (hereafter known simply as Alpha releases), please use Mantis instead of posting to the forums. This is a relatively new procedure as of July 29th, 2011.

Start Off on the Right Foot

1. We highly recommend signing up for a Mantis account early on. It makes participating in issue reporting activities much easier, and it does not take much time.
2. Once you have a Mantis account, log in.

Search Existing Issues

1. Open the View Issues page in Mantis.
2. Below the first table -- its rows have alternating colors -- on the left side, you should see a Search box. Type one or two key words related to the issue you are experiencing into that box.
3. Click the Apply Filter button, which is either to the right of or just below the Search box.
4. After the page loads, you should see a second table titled Viewing Issues below the Search box.

Hints for Keywords to Try

If you are dealing with a Stack Report, try searching for one or two of the words or symbols in the second paragraph of the Stack Report, before the line containing "Version:".

If you are reporting Unexpected Behavior with certain cards, you could enter one or two words of the cards' name(s) into the box. For example, if the problem is in Sphinx-Bone Wand, you could try "sphinx" "wand" or just "wand" (either with or without the quotes). Or, try using words that describe the card(s), rather than the cards' names. For example, with Sphinx-Bone Wand, you might want to search for "charge" "counter".

No Matching Issues

1. If the second table shows Viewing Issues (0 - 0 / 0), your search did not match any open issues. Try searching with different key words.
2. If you still get no matching issues, then you should File a New Bug Report.

Read the Issues

1. Read through the summaries of the issues in the second table. If one of the summaries sounds like yours, click its ID number in the fourth column to get more details.
2. If the issue turns out not to be the same, use the Back button in your web browser to read the other issues.
3. If no issues match, try using different words in the Search box as explained in the No Matching Issues section.
4. If you do find a matching issue, think about whether you can add any helpful information to it.
5. In any case, you can click the Monitor button to get email alerts about changes and updates to the issue.

Add a Helpful Note

1. Scroll down to the Add Note table.
2. Enter your text into the box there. For a bug, try to describe the specific steps you took to produce or reproduce the error.

File a New Bug Report

1. If you could not find an existing issue that matches yours, Report a new issue.
2. Choose the Category corresponding to the issue type: New Stack Report, New Unexpected Behavior, or New Feature Request.
3. If you are reporting a bug, and you are able to reproduce the problem, check the value next to Reproducibility that best fits your efforts. If you have not tried to reproduce it, that is OK. For Feature Requests, choose N/A.
4. For Severity:
   1. If you are reporting a Stack Report, choose crash.
   2. For a Feature Request, choose feature.
   3. For Unexpected Behavior, use your best judgment.
5. Skip Priority.
6. If you know your processor's type, place it next to Platform.
7. Enter the name of your OS next to Operating System. For example, "Windows Vista" (no quotes).
8. If you know the specific version of OS that you are running, place it next to OS Version. If not, leave it blank.
9. For Product Version:
   1. If you are reporting an issue for the latest Beta version of Forge, choose the version from the drop-down list.
   2. If you are reporting an issue for an Alpha release of Forge, choose Git.
10. Enter a descriptive Summary of the issue. For Stack Reports, include words found in the second paragraph.
11. For Description:
    1. For Stack Reports, paste the entire Stack Report here.
    2. For Unexpected Behavior and Feature Requests, enter a more wordy description, but do not include the steps to reproduce the problem.
12. For Steps to Reproduce:
    1. For Stack Reports and Unexpected Behavior, try to identify a simple sequence of steps to help someone else experience the same problem. Issues that developers can easily reproduce are much easier to solve.
    2. For Feature Requests, leave this blank.
13. If you chose Git for the Product Version, skip down to Detected at Git Rev. Enter the 7-character code for the Git revision you are alpha testing.
14. Click Submit Report.

You will be notified via email when changes are made to any reports you have submitted. To change this, open the issue and click the End Monitoring button.

Thank you for helping make Forge better!