Reporting Bugs

The Aleph One wiki has migrated! Please see:
https://github.com/Aleph-One-Marathon/alephone/wiki/Reporting-Bugs

What should you do if Aleph One crashes? Generally, you should inform the developers. Read this page for a general guide on how to file a bug report on Sourceforge.

Run the latest version

Before submitting a report, make sure your bug hasn't already been fixed. Check the main page for the latest version of Aleph One. If your version is out of date, upgrade and try the same steps that led to the crash. Bugs reported for old versions will be ignored.

Reporting a bug

  1. Go to the Source.Bungie.Org page, and click on Bugs
  2. Scan through the bugs to make sure you're not reporting a known issue
  3. Login to sourceforge / create an account
  4. Click "Create Ticket" in the left sidebar
  5. Enter a brief but descriptive title. Please file separate reports for each bug.
    • Good example: "Screen doesn't dim on pause"
    • Bad example: "OpenGL doesn't work"
  6. Enter a detailed description. List things like:
    • What operating system you are running
    • Your CPU and video card specs
    • What build and version of Aleph One
    • Which scenario you are using, and where you got the data files
    • Whether your bug is reproducible or not, and if it is, how to reproduce it
    • If the bug is a crash bug, read the Crashes section to get more information on how to report crashes
  7. Upload useful files such as
    • A crash report if there is one (see Crashes)
    • The relevant part of the log file (see Crashes)
    • Screenshots if relevant
    • If you have a film that demonstrates the problem, include the film, and also the map if it's not part of a commonly available scenario
  8. Leave the other options (status, owner, priority, etc.) set to their defaults
  9. Click "Save" to submit the bug
  10. Make sure to check the bug's comments in the future, in case there are questions

Crashes

These are the two ways that Aleph One exits unexpectedly. Read the sections below for a description of each, and then continue on to learn how to determine which happened and what to add to your bug report.

Assertion failures

These happen when Aleph One does an internal consistency check, and finds something so seriously wrong it can't continue. Assertion failures always print a message to the log file, but often they are in very generic places in the code so the message isn't always helpful.

If Aleph One quits because of an assertion failure, it will show up in the log file. Copy the assertion failure part of the log to the sourceforge bug report, or upload the relevant part of the log file.

Also, if you were in a solo game when Aleph One encountered an assertion failure, you can save a film of the assertion by starting Aleph One up, and choosing "Save Last Film". Attach the film to the bug report, and also the map if it's not a well-known or widely-available scenario.

Mac OS X

The log file is located in your home directory's Library/Logs folder, named Aleph One Log.txt. If you're using an all-in-one build, then it will be named after the game, such as Marathon 2 Log.txt.

Windows

The log file is located in your "My Documents" folder, named Aleph One Log.txt. If you're using an all-in-one build, then it will be named after the game, such as Marathon 2 Log.txt.

Linux / *nix

The log file is located in your ~/.alephone directory, named Aleph One Log.txt. If you're using an all-in-one build, then it will be named after the game, such as Marathon 2 Log.txt.

Application crashes

Application crashes occur when the operating system performs a consistency check on Aleph One and finds something seriously wrong. Since they are unpredicted (unlike assertion failures) they don't print an error message to the log file. A crash reporting tool is necessary to figure out why Aleph One is crashing.

Mac OS X

Mac OS X includes a built-in crash reporter, that will pop-up when Aleph One crashes. Click on "Report..." and you'll get a crash report. Attach that text to the bug you file.

It doesn't hurt to submit bugs to Apple. They often times can trace framework or other system-level crashes by using aggregate and other comparative tools. In short, Apple may not care about A1, but it still can provide them with useful crash data when looking at the "big picture". Apple encourages you to share reports with them whenever a program crashes.

Windows

In order to get crash reports in Windows, you need to copy this file to the same folder as Aleph One.exe, and try to get it to crash again. If it crashes, a TEST.RPT file will be saved. Attach TEST.RPT to the sourceforge bug.

Linux

You can run Aleph One in gdb:

$ gdb ./alephone
(gdb) run -d

and when it crashes, type:

(gdb) bt

Copy the backtrace into the sourceforge bug report.


Related

Wiki: Home