Skip to content

Reporting Bugs

Jump to bottom
Jeremiah Morris edited this page Aug 20, 2015 · 2 revisions

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 GitHub.

Run the latest version

Before submitting a report, make sure your bug hasn't already been fixed. Check the Aleph One home 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 Aleph One home page, and click on Bugs
  • Scan through the bugs to make sure you're not reporting a known issue
  • Sign in to GitHub, or create an account
  • Click the green "New Issue" button in the top right corner
  • 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"
  • 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
  • Add any relevant screenshots of Aleph One, or of your scenario directory in Explorer or Finder if you can't get a scenario to load.
  • If you have a crash report or log file (see Crashes), upload them to a service like Gist or Pastebin, and provide a link in the description.
  • If you have other useful files, upload them to a service like Dropbox, and provide a link in the description.
    • 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
  • Click "Submit new issue" to file the bug
  • 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 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". Upload the film, 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 Aleph One, 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. Upload TEST.RPT and link to it in the bug description.

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 bug report.

Clone this wiki locally