Tips on Reporting Bugs

To report any bugs you find in TADS, please use the TADS Bug Database. Please don't send us bug reports by email - the database is a much better way to communicate about bugs, since it keeps all of the bug information in one place, and it creates a record that anyone can view.

What counts a bug?

If TADS crashes, it's probably a bug. "Crashing" means that the program freezes up the machine, forces the machine to reboot, or terminates abruptly with a technical-sounding error message from the operating system ("sigsegv", "core dumped", "general protection fault", etc).

Exception: If you're writing a game, and the machine seems to freeze up while the game is running, it's possible that you've written an "infinite loop" in your code. This isn't a TADS bug - TADS can't really stop you from writing infinite loops, since for all it knows, that could be what you really wanted to do!

If you're running into a freeze, and you suspect that it's due to an infinite loop in your own code, try this. Fire up the game in Workbench (if you're using Windows) and do whatever causes the freeze to occur. Once the machine appears to be stuck, press Ctrl+Break - if the game code is looping, this will interrupt the loop and break into the debugger, which not only un-sticks the machine, but also shows you exactly where the never-ending loop is in your code.

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

If TADS doesn't behave according to the documentation, it's a bug. Sometimes it's hard to tell for sure whether a particular behavior is right or wrong, since there are inevitably gaps and ambiguities in the documentation. When in doubt, feel free to contact us by email if you want a second opinion before reporting a bug.

Check for existing reports

Before you report a bug, please check the database for an existing report of the same problem. You can search the bug list for keywords relevant to your bug, for example.

The benefit to us of avoiding duplicate reports is fairly obvious. There's also a benefit to you, though, too: a past report of the same bug might include information you can use, such as a way to work around the problem, or news that the problem is fixed in a recent or upcoming version.

Include a test case

The most important piece of information in a bug report 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, and unfortunately our travel budget doesn't allow us to come to your house and watch over your shoulder while you demonstrate the bug. So, we have to be able to make the bug happen on our own machines - we have to "reproduce" the bug here.

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. Tell us all the gory details - the full command lines you're typing, the exact source code involved, etc. Tell us step by step what we have 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 someone who's never used TADS.

If the bug is related to a game you're writing, please include the source code involved. (But 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 further before sending us all of that information.

Most of the time, when you find a bug, it will exhibit some kind of pattern. The bug won't merely happen in your complete game - it will happen in any game containing whatever the key feature is that triggers the bug.

It's not always easy to figure out exactly what that triggering condition is, but sometimes it's fairly obvious. For example, if you compile your code one minute, then you make a small change and compile again, and TADS crashes the second time, there's a good chance that something about that small change is 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" - it's the smallest possible test case that triggers the bug. For example, if you find that TADS simply can't handle a local variable named "xyz", you could create a tiny program that's simply a "main" function with a local variable of the offending name - if you can then compile that tiny program and the bug still happens, 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

If you're using Windows, and TADS crashes with a Windows error (such as "tc32.exe encountered a serious problem and must terminate"), there might be some useful information left behind from the crash. Look in your game and/or TADS directory for a file called TADSCRSH.TXT - this file contains information about the part of the TADS application that was executing when the crash occurred. If you find this file, and its timestamp matches the time of the crash, include the contents with your bug report.

Reporting multiple bugs

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 different handling.