## Reporting Bugs

So you think you found a bug in Colossus? You're not alone. The program is still an alpha release. It definitely has bugs.

That said, we get more incorrect or duplicate or outdated or otherwise not very useful bug reports than we get good bug reports. If you'd like to increase the chances that the bug you found gets fixed soon, you want to make sure your bug report is a good one.

#### Rules for good bug reporting

- Make sure you're running current code.

- If you're running a month-old build of the game, then it's likely that your bug has already been fixed. Try the latest release before reporting bugs. (If you use Java Web Start, it automatically grabs new versions from time to time. To force it to update, just run the game several times in a row.)

- Use the SourceForge trackers, not email

- Email is great. We like getting email from Colossus players. And we welcome user comments on the Colossus developers list. But bug reports sometimes get lost among all that other email.

  The SourceForge Bug Tracker is the central repository for the project's bugs. If you put your bug there, then we don't have to. Other users will see that it's there, so they can add detail to your bug report, rather than sending duplicate bug reports. All developers will see the bug, not just the one you sent email to.

- Check to see if your bug is already there, rather than filing a duplicate report.

- If we can get all the data about one bug into one bug report, that increases our odds of fixing it quickly. Duplicates are annoying. If you have more information, add it to the existing bug report.

- Don't put multiple unrelated bugs in the same report.

- One report per bug, please. If you put two bugs in the same report and we fix one, we can't mark it closed.

- Feature requests are welcome, but they're not bugs.

- We have a separate Feature Request tracker . If the game crashes doesn't play by the Titan rules or clearly doesn't work as designed, that's a bug. If you have an idea for an improvement, that's a feature request. Filing your feature request as a bug is annoying. Again, it's a good idea to scan the existing feature requests and avoid posting duplicates, and put one feature request per report. And remember that this is a free project done in our spare time -- we can't do everyone's pet feature. (But feel free to add it yourself.)

- Support requests are welcome, but they're not bugs.

- If you need help getting the game to run on your computer, or need something explained, and you've read the docs , then feel free to send email. We don't use a tracker for this yet.

- Select a category for your bug report

- We only have a few categories. Many bugs fall under "General" so pick that if it's not clearly one of the others. If you pick a category, the the appropriate person will automatically get email notification of the bug report. If you don't, then nobody gets notified, and it might be a while before someone sees your report.

- Select a reasonable severity for your bug report.

- Severity ranges from 1 (lowest) to 9 (highest). Default is 5. Most bugs can be left at the default. If it's a repeatable crash bug, feel free to knock it up to 6 or 7. If it's just a little nitpick that doesn't make the game unplayable, knock it down to 2 or 3. But if you automatically set all your bugs to high priority because you can, then we'll just knock them back down and call you a weenie.

- Always include your operating system and Java version

- Java is a pretty portable language. Sun's slogan for it is "Write Once, Run Anywhere." Unfortunately, perfect portability is an elusive goal. Experienced Java programmers known the reality of "Write Once, Debug Everywhere."

  Some bugs are caused by universally bad logic. Those ones occur on every machine. Note that the developers do test the game, so such bugs tend to be found quickly. (Unless they're in rarely-visited corners of the game logic.)

  Other bugs happen only on some operating systems, or some Java versions. These ones are a lot harder to find. If you always report your OS (e.g. "Windows 98") and Java version (e.g. "1.4.1") then we can try using the same ones (if we have access to them) and possibly see the bug more quickly. (Note: if you don't know your Java version, you can find it by running the game then selecting Help/About.)

- If possible, login to SourceForge before reporting a bug

- We do allow bug reports from users who aren't logged in. But if someone reports a bug and doesn't give us any contact info, then we can't ask questions. Also, bugs reported by bug reporters with a track record might get attention sooner than bugs reported by random people. And we can't put you in the credits if we don't know who you are.

  SF is a very good system, used by a lot of free software projects. And they respect their users' privacy. It's worth the bother of registering. If you won't register, then please stick your email address in your bug reports. And if you are registered, check to see that you're logged in before you file a report. (SF now has a "Remember Me" option.)

- An exception trace is worth a thousand words.

- If the game crashes, there's often a Java exception trace. Unfortunately, modern GUIs tend to hide stuff like this from users. So you need to learn how to catch them.

  If you use Java Web Start, the trick is to start up the Java Web Start console, select File/Preferences/Advanced, check "Log Output", and pick a filename (like c:\jws.log, or /tmp/jws.log). Then all programs run by Java Web Start, including Colossus, will dump information there. (The file will eventually get big, so you might want to delete it from time to time.) If the game crashes, copy the last part of this file (a few dozen to a few hundred lines) into the bug report.

  If you don't use Java Web Start, then if you want to see exception traces you need to start the game from a command prompt window (e.g. "java -jar Colossus.jar" instead of by double-clicking on the jar file in a file manager. Error output (along with a lot of other stuff) then goes to that window. See the README for more details about running the game this way. If you're not a hardcore computer person, then the Java Web Start method is easier.

  Note that there is also a file called lastgame.log in your {user.home}/.colossus directory. (If you don't know your {user.home}, try Help/About.) Unfortunately, for technical reasons we haven't been able to get exception traces to go there. But if you don't have a full trace, the end of that file might still have something useful.

- A savegame sometimes helps too.

- Some bugs occur only in particular game situations, like when summoning an Archangel. Getting the game to that state can sometimes take a while. If you have a savegame from right before the bug occurred, this can help us reproduce the bug. Please attach it to the bug report. (Our savegames are pretty big, so you definitely need to attach rather than cut-and-paste.) But if you can easily get from the start of your game to your bug in a couple of minutes, there's no need to attach a savegame.

- Describe exactly how to reproduce the bug.

- If the bug is repeatable but only in odd situations, describe exactly how to make it happen. The more detail you give, the more likely we can do it too without having to contact you for more help. If the bug is intermittent (sigh), tell us that, so we don't think you're crazy when we try the same steps and don't get the same results.

- We already know the AI is weak.

- We get a lot of bug reports saying that the AI did something dumb. We know. General whining about this isn't very helpful. Very specific bug reports on exact low-level bad decisions it made might be helpful.

Thanks for reading this, and thanks for reporting bugs.