Tips on Reporting Bugs

Here are some tips on reporting bugs through the TADS Bug Database. These guidelines are meant to help you enter reports with all of the information we need to begin investigating, so that we can respond quickly and efficiently.

Set up a user account

You'll have to set up a bug db user account to enter bug reports. Note you have to create a separate bug db account even if you have an IFDB account. We unfortunately can't provide a single sign-on, because Mantis (the bug tool we use) maintains its own separate user list.

Check for existing reports

Before you report a bug, it's a good idea to search the database for an existing report of the same problem. If it's already been reported, you save both of us time by avoiding a redundant report. You might also find an immediate workaround or patch, or other useful information, if the problem is already known.

Report separate bugs separately

If you've run into several bugs, please file a separate report for each one. This lets us track each issue individually, which is important because each issue might need separate handling.

What counts a bug?

There are often two programs at work when you're using TADS: TADS itself, and the game program that TADS is compiling or running. When something goes wrong, it's not always obvious whether the problem is in TADS or in the game. The TADS bug database is only for reporting TADS problems; bugs in a game should be reported to the game author instead. This section tries to help clarify which is which.

If TADS crashes, it's probably a TADS bug. "Crashing" means that the program forces the whole computer to reboot, or terminates abruptly with an error message from the operating system. On Windows, the system usually displays a dialog box with a message such as "TC32.EXE encountered a serious problem and must terminate." On Linux, the message is usually something like "SIGSEGV caught" or "core dumped". Sometimes there's not even an error message; the program simply terminates unexpectedly.

If TADS freezes up, it's probably a TADS bug. "Freezing" means that TADS, or your whole computer, becomes unresponsive to all input for an extended period. If it's only for a few moments, that's not a freeze; it's probably just some heavy computation. A freeze is when it goes on long enough that you're pretty sure it's permanent.

Exception: If you're writing a game, and you accidentally code an infinite loop, it's your game that's frozen, not TADS. If you suspect that a freeze is due to an infinite loop in your own code, try this. Run the game in Workbench (if you're using Windows) and repeat the steps to trigger the freeze. Once the game is stuck, press Ctrl+Break. This will interrupt a game loop and break into the debugger. This not only un-sticks the machine, but also shows you exactly where in your code the loop is occurring.

Errors reported by TADS itself (rather than by the operating system) aren't crashes, but they might still be TADS bugs. If the message indicates that something unexpected has happened within TADS, it's likely a bug. Error messages that point out errors in your input usually aren't TADS bugs - but if you're convinced that what you're doing really is correct, and that TADS is wrong to reject it, that could be a TADS bug.

If TADS does something contrary to the documentation, it's a TADS bug. Sometimes it's hard to tell for sure whether a particular behavior is right or wrong, since the documentation is sometimes ambiguous. When in doubt, feel free to contact us by email if you want a second opinion.

Include a test case

The most important thing we need to know is how to reproduce the problem. In most cases, the only way we can figure out what's causing a bug is to see it in action. We have to be able to make the bug happen on our own machines, which is called "reproducing" the bug.

The best way to help us reproduce a bug is to include a test case. A test case is the exact and complete set of steps that triggers the bug. We need to know exactly what you're doing: the full command lines you're typing, the full source code involved, etc. Tell us step by step what to do. Sometimes a bug will only show up if everything is done exactly a certain way, so try to include as much detail as you can in your instructions. Pretend you're explaining the procedure to your computer-phobic great aunt.

If the bug is related to a game you're writing, please include the source code involved. (See the note below about "minimal" test cases.)

In some cases, you might encounter a bug that you can't even reproduce yourself, let alone explain to someone else. In these cases, be as specific as you can about the conditions leading up to it. Include a screen-shot if that would help explain anything.

Include any other information that you think is relevant. For example, if you were running a bunch of other applications at the time, and you think the system was low on memory as a result, that might be important - the problem might just be that TADS ran out of memory and didn't recover gracefully enough.

Find the minimal test case, if possible

The easiest thing to do when you find a bug is to stop what you're doing, ZIP up all of your files, and send them all along with the bug. However, it's a big help to us if you can narrow things down a little bit first.

The key is to figure out the specific thing in your game that's triggering the bug, and send us a small example with just that one specific thing. Sometimes it's easy to identify a specific trigger, sometimes it's not. For example, if your code starts off compiling fine, but it stops compiling after you make one small change, that small change you just made is probably the trigger. Or, if TADS gives you an error message that seems wrong, the problem is probably at or near the line of code flagged in the error message.

If you can isolate the triggering condition for the bug, you might be able to create a very small example that demonstrates the bug. This is what we call a "minimal test case" - the smallest test case that triggers the bug. For example, if it appears that the compiler crashes any time there's a local variable named "xyz", try creating a program that's simply a "main" function with a local variable "xyz": if the compiler crashes when you compile this little program, you have an excellent minimal test case.

The more you can isolate a bug in this manner, the easier it will be for us to fix it. Now, the trade-off is obviously that you'll end up spending more time researching the bug, and we certainly don't intend for you to spend hours at this. If it's not fairly obvious how to narrow down the bug, just send us the full-game test case.

Crash errors on Windows

On Windows, a crash sometimes leaves behind useful debris. Look in your game folder and/or TADS directory for a file called TADSCRSH.TXT. This is TADS's version of the "black box" that you hear about in aviation accidents. It records information about what was going on inside the software at the time of the crash, which can sometimes help us isolate the cause. If you find this file, and its file timestamp matches the time of the crash, please include the contents with your bug report.