Revision as of 01:21, 8 August 2011

About This Document

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

Most users, who are running beta versions of Forge, should continue to use these instructions. Alpha testers should also continue using this document until the Steps to Reproduce field has been made available in Forge's own bug reporting feature.

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 the following benefits:

1. It is a clean way to comment on issues as they evolve.
2. It reduces the number of duplicated issue reports.
3. It greatly enhances the visibility of both old and new issues to the Forge developers.

Tutorial

What Kind of Issue Is It?

There are four major kinds of issues that the Forge developers want to keep track of. The first three are also sometimes called bugs. The general term for any of the three is "issue".

Please determine your issue's category before reporting it.

A Crash 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" or "Crash Report", we call this a "Crash Report". These are sometimes called by other names: "crashes", "stack reports", "stack traces", "error messages", etc.

A Card or Rules Bug

If you did not get a Crash Report, but you have experienced a problem in how Forge handled one or more cards or game rules, we call this a "Card or Rules Bug". Before reporting a bug of this kind, 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.

Incorrect Opponent Behavior

This category includes all the cases where the Computer opponent makes a bad, silly, or downright ridiculous decision in its efforts to thwart you.

A 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".

Sign Up

1. If you want email updates when certain bugs have changed, or if you want to report bugs using Mantis (instead of through Forge itself), you must sign up for a Mantis account. Besides, 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

If you have already checked that your issue has not yet been reported in Mantis, skip to the File a New Issue Report section.

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 Crash Report, try searching for one or two of the words or symbols in the second paragraph of the Crash Report, before the line containing "Version:".

If you are reporting a Card or Rules Bug 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 skip to File a New Issue 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.

How to Add a Helpful Note

If you have something helpful to add to an existing issue:

1. Search for and open the issue.
2. Scroll down to the Add Note table.
3. Enter your text into the box there. For a bug, try to describe the specific steps you took to produce or reproduce the error.
4. Click Add Note below the box.

File a New Issue Report

Although Forge itself currently has the capability to report issues into Mantis, we do not recommend using it, because it does not support the Steps to Reproduce field.

If you could not find an existing issue that matches yours, Report a new issue in Mantis.

Here is some help on what values to enter for in the various boxes:

Category

• This must correspond to the issue type. Use New Crash Report, New Card or Rules Bug, New Incorrect Opponent Behavior or New Feature Request.

Reproducibility

• If you are reporting a bug, use the value that best fits your efforts. For Feature Requests, choose N/A.

Severity

• If you are reporting a Crash Report, choose crash.
• For a Feature Request, choose feature.
• For the other categories, use your best judgment.

Priority

• Skip this one.

Platform

• A processor type, such as "x86" (for most PCs) or "ARM". If unsure, leave this blank.

Operating System

• For example, "Windows Vista" (no quotes).

OS Version

• The specific version of OS that you are running. If unsure, leave this blank.

Product Version

• If you are reporting an issue for the latest beta release of Forge, choose the version from the drop-down list.
• If you are reporting an issue for an alpha release of Forge, choose Git. Also, scroll down to Detected at Git Rev. Enter the 7-character code for the Git revision you are alpha testing, if you know it.

Summary

• Summarize the problem itself, not what you think the solution might be. For Crash Reports, include words found in the second paragraph.

Description

• For Crash Reports, paste the entire Crash Report text into this box.
• For the other issue types, enter a more wordy description, but do not include the steps to reproduce the problem.
• You can include speculation here about the cause of the problem.

Steps to Reproduce

• For Feature Requests, leave this blank.
• For all other categories, 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!

You may skip the other boxes.

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!