Revision as of 03:48, 27 January 2020

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.

Using an issue tracker provides the following:

It is a clean way to comment on issues as they evolve.
It reduces the number of duplicated issue reports.
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

If you want email updates when certain bugs have changed, or if you want to report bugs using Gitlab (instead of through Forge itself), you must sign up for a Gitlab account. Besides, it makes participating in issue reporting activities much easier, and it does not take much time.
Once you have a Gitlab account, log in.

Search Existing Issues

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

Open the View Issues page in Gitlab.
Right below the Open tab, you should see a Search box. Type one or two key words related to the issue you are experiencing into that box.
Press enter to search

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?

If the table shows np results, your search did not match any open issues. Try searching with different key words.
If you still get no matching issues, then you should skip to File a New Issue Report.

Read the Issues

Read through the summaries of the issues in the table. If one of the summaries sounds like yours, click its ID number in the fourth column to get more details.
If the issue turns out not to be the same, use the Back button in your web browser to read the other issues.
If no issues match, try using different words in the Search box as explained in the No Matching Issues? section.
If you do find a matching issue, think about whether you can add any helpful information to it.
In any case, you can click the Notifications 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:

Search for and open the issue.
Scroll down to the Add Note table.
Enter your text into the box there. For a bug, try to describe the specific steps you took to produce or reproduce the error.
Write a new comment in the dialog box.

File a New Issue Report

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

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

Choose a template (either bug report or feature request) then follow the template by filling in as much information as you have.

Also try to provide things like...

Product Version or just Version

The version is either a "snapshot" or a "release" and wherever you downloaded Forge should list the version numner.

Summary

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

Description

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!

@@ Line 9: / Line 9: @@
 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:
+Using an issue tracker provides the following:
 # It is a clean way to comment on issues as they evolve.
 # It reduces the number of duplicated issue reports.
@@ Line 40: / Line 40: @@
 == Sign Up ==
-# 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'' [http://www.cardforge.org/bugz/signup_page.php sign up for a Mantis account]. Besides, it makes participating in issue reporting activities much easier, and it does not take much time.
+# If you want email updates when certain bugs have changed, or if you want to report bugs using Gitlab (instead of through Forge itself), you ''must'' [https://git.cardforge.org/users/sign_in?redirect_to_referer=yes#register-pane sign up for a Gitlab account]. Besides, it makes participating in issue reporting activities much easier, and it does not take much time.
-# Once you have a Mantis account, [http://www.cardforge.org/bugz/login_page.php?return=%2Fbugz%2Fview_all_bug_page.php%3F log in].
+# Once you have a Gitlab account, [https://git.cardforge.org/users/sign_in?redirect_to_referer=yes 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|File a New Issue Report]] section.
+If you have already checked that your issue has not yet been reported in Gitlab, skip to the [[#File a New Issue Report|File a New Issue Report]] section.
-# Open the [http://www.cardforge.org/bugz/view_all_bug_page.php View Issues page in Mantis].
+# Open the [https://git.cardforge.org/core-developers/forge/issues View Issues page in Gitlab].
-# 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.
+# Right below the Open tab, you should see a Search box. Type one or two key words related to the issue you are experiencing into that box.
-# Click the '''Apply Filter''' button, which is either to the right of or just below the Search box.
+# Press enter to search
-# After the page loads, you should see a second table titled '''Viewing Issues''' below the '''Search''' box.
 === Hints for Keywords to Try ===
@@ Line 60: / Line 59: @@
 === No Matching Issues? ===
-# If the second table shows '''Viewing Issues (0 - 0 / 0)''', your search did not match any open issues.  Try searching with different key words.
+# If the table shows np results, your search did not match any open issues.  Try searching with different key words.
 # If you still get no matching issues, then you should skip to [[#File a New Issue Report|File a New Issue Report]].
 === Read the Issues ===
-# 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.
+# Read through the summaries of the issues in the table. If one of the summaries sounds like yours, click its ID number in the fourth column to get more details.
 # If the issue turns out not to be the same, use the Back button in your web browser to read the other issues.
 # If no issues match, try using different words in the Search box as explained in the [[#No Matching Issues?|No Matching Issues?]] section.
 # If you ''do'' find a matching issue, think about whether you can add any helpful information to it.
-# In any case, you can click the '''Monitor''' button to get email alerts about changes and updates to the issue.
+# In any case, you can click the '''Notifications''' button to get email alerts about changes and updates to the issue.
 == How to Add a Helpful Note ==
@@ Line 78: / Line 77: @@
 # Scroll down to the Add Note table.
 # Enter your text into the box there.  For a bug, try to describe the specific steps you took to produce or reproduce the error.
-# Click '''Add Note''' below the box.
+# Write a new comment in the dialog box.
 == File a New Issue Report ==
-If you could not find an existing issue that matches yours, [http://www.cardforge.org/bugz/bug_report_page.php Report a new issue in Mantis].
+If you could not find an existing issue that matches yours, [https://git.cardforge.org/core-developers/forge/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D= Report a new issue in Gitlab].
 Here is some help on what values to enter for in the various boxes:
-'''Category'''
+Choose a template (either bug report or feature request) then follow the template by filling in as much information as you have.
-* 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'''
+Also try to provide things like...
-* 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''' or just '''Version'''
-* If you are reporting an issue for the latest beta release of Forge, choose the version from the drop-down list.
+* The version is either a "snapshot" or a "release" and wherever you downloaded Forge should list the version numner.
-* If you are reporting an issue for an alpha release of Forge, choose '''SVN'''. This stands for Subversion, which is the software Forge uses to track changes to its files. Also, scroll down to '''Detected at SVN Rev''' or '''SVN rev.'''. Enter the ''number'' for the SVN revision you are alpha testing, if you know it.
 '''Summary'''
@@ Line 133: / Line 112: @@
 '''Thank you for helping make Forge better!'''
-== Email Alerts ==
-By default, you will ''not'' be alerted by email when an issue changes, even if you were the one to report the issue.
-To start or stop getting email alerts about any issue, search for and view the issue. Click the '''Monitor''' button to start the email alerts, and the '''End Monitoring''' button to stop them. The button is usually about 3/4 the way down, in the same row as the Edit button.

Difference between revisions of "Forge: How to File an Issue Report"