Essential to helping us identify and fix bugs is the ability to not just notice bugs, but to identify them in a way that makes it as easy as possible for us to see it. The adage here is “we can’t fix what we can’t see.”

This page contains guidelines on how to create incredibly useful bug reports. If you follow these guidelines, you’ll make it easier for us to see your bug and therefore to fix it quickly.

Keep in mind that when switching from Classic to OS X Helix, views may look significantly different, but they should act the same. If they don’t, you may have found a bug.

We tried to maintain the familiar Helix functions as much as possible, but some changes are forced upon us, either by OS X or wxWidgets. So when something appears to be different about the interface, check the Release Notes to make sure it isn’t a Specification Change or a Known Problem.

Also keep in mind that this preview release has some features disabled. The surveys we conducted let us know that we should focus on getting key features working and release something as soon as possible, leaving some of the other items (like Document Management) for a subsequent release. If you encounter a ‘missing feature’ Helix should pop up a dialog box offering our apologies.

Because the focus of this release is the switch to OS X, the first question you should always ask when you encounter something unusual is: How Does it Work in Classic? With the exception of things we have specifically noted in the Release Notes, OS X Helix should act the same as Classic Helix.

So when you see something odd, your first step should be to go back to Classic and confirm that the behavior you expected is really what Classic does. (We fooled ourselves into thinking we knew how Classic acted in certain situations enough times that we know it will happen to you too.) Because Helix 6.0 and Helix 6.1 are completely code-compatible, you can easily move your collections back and forth between Classic Helix RADE (or Engine) in 6.0.x and OS X Helix Engine in 6.1.

Only after you have confirmed that the behavior is wrong (or at least different in a way that is not documented in the Release Notes) should you move on to actually submitting a report.

The very best reports include the following (in order):

1. Identify the expected behavior. (What I expected)
2. Identify how the new version deviates from the expected. (What happened)
3. Provide clear instructions on how to reproduce the bug. If possible, send a sample collection showing the bug in action.

Be sure to use accurate terminology. Helix is a visual language and we have learned that many people have invented their own words to describe the objects in a Helix collection, and that is fine, but telling us something like ‘the rejector is wrong’ is infinitely less helpful that saying ‘validations are failing.’

Taking “we can’t fix what we can’t see” to heart, the best reports include a small sample collection that shows the bug in action. That is not always possible, but when it is, use these guidelines:

• Make it as simple as possible. Don’t send us your 20MB collection that contains 50 relations and 500 views with a note that says, in effect, there’s a bug in here somewhere. When you see a bug, your first thought should be “Can I reproduce this in a small collection built from scratch?” If you can do that, you’ve got a bug we can fix in hours, not days.
• If attempting to recreate it from scratch doesn’t work, try to Isolate the problem. Make multiple copies of the suspicious code and start removing the extraneous bits from the view. Countless times we have discovered that a bug was not caused by what our original impressions told us. Only by paring it down to the simplest elements were we able to zero in on the real issue. Debugging a problem on a view with 5 rectangles is a whole lot easier (and faster) than on one with 100.
• If attempts to trim it down fail, then by all means send us the whole collection. But if you have to do that, then the next set of instructions are all the more critical
• Any time you send us any collection, please document the bug directly in the collection, preferably right on the view where the bug is seen. Do not send us a collection without internal notes! (Putting the notes in a text edit file and zipping them together does not count!) After a collection comes to us, it may be routed to various people to work on. Only by putting the instructions directly in the collection can you guarantee that the person looking at the bug has all of the pertinent information. Please remember that you know your collection far better than we do, so sending a collection with instructions to ‘run the end of month summary report’ is only going to result in delays. This screenshot should give you a good idea of what we like to see.
• Put command keys on all relevant menu items. We request that you make F5 the ‘first keypress’ for all examples. Put your documentation in that view. Anybody assigned to working on your bug should be able to open the collection, press F5, and be able to come up to speed without having to refer to external documentation.
• Documentation should refer to items by name, not by menu position. (Write: View ‘Data Entry’ in menu ‘Testing’, not the first item in the testing menu.)
• Documentation should explicitly state which command key opens which view. (Write: View ‘Data Entry’ (F5) in menu ‘Testing’ shows the problem)
• Don’t put menu items in hierarchical menus — unless the bug is related to hierarchical menus! Your sample shouldn’t be so big that it needs them and they just slow down the process. If it is, please take the time to move the pertinent items to a common menu so we can easily find them.

Once you've got the perfect sample collection, how do you get it to us? One of two ways:

1. If the collection is under 5MB, attach it directly to your bug report in our bug reporting database. The Support Documents section is designed for this very purpose.
2. If the collection is larger than 5MB, use the instructions for sending collections for repair to upload it to our repair server. But where those instructions say to refer to your TS case number, refer to your bug’s R (report) number.

When Helix crashes, it should display a dialog telling you ‘A nnnn error occurred’ — please do not take a screenshot of that dialog and upload it! Write down the code and click the Quit button. Helix should then go into a spin and then crash. That is where the useful information is gathered. Follow the instructions on the How to Report OS X Crashes page to get the crash log and attach that as a supporting document to your beta report. Again: No Screenshots!

A picture is worth a thousand words, so include OS X vs Classic screen shots if there is a difference worth illustrating. This sample shows some discrepancies between the two renditions of the same view.

If you do this, be absolutely certain that you include a screenshot of the Classic version so we have something to compare to. And please try to describe the problem; don’t just upload a picture with a report that says ‘this doesn't look right.’

Of course, not every bug can be isolated down to a simple test case. We know that, and we don’t want to discourage you from sending your reports because you can’t seem to isolate the bug. Just keep in mind that the more you do to help us see the bug, the faster we can fix it. And that helps everybody.

Thank you.

Our How To Get Your Bug Fixed page.