Essential to helping us 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 a useful sample collection that document the bug you have found. If you follow these guidelines, you’ll make it easier for us to see your bug and therefore to fix it quickly. For us, the first rule is: bugs that are easy to reproduce get top priority. (Well, bugs that impact data integrity get higher priority, outside of beta testing, those are rare.)

Keep in mind that there are some changes when switching from Classic to OS X. These are not necessarily bugs. We tried to maintain the familiar Helix functions as much as possible, but some changes are forced upon us by OS X. If something is different, check the Release Notes to make sure it isn’t a Specification Change or a Known Problem.

The very best reports should:

1. Identify the expected behavior. (What was expected)
2. Identify how the new version deviates from the expected. (What actually happens)
3. Provide clear instructions on how to reproduce the bug. (How to see it again)

When writing instructions, 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 for your personal use, but telling us something like ‘the rejector is wrong’ is infinitely less helpful than saying ‘validations are failing.’

A small sample collection that shows the bug in action and contains instructions on reproducing the bug is guaranteed to get our immediate attention. 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, work to isolate the problem. Make copies the collection and strip the template down to only what is necessary to see the bug. Delete unneeded icons from the relations. 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 are we able to zero in on the real issue. Debugging a problem on a view with 5 rectangles is significantly faster than on one with 100. Yes, this can be a lot of work, but remember that the more you do to make it easy for us to see the bug, the faster we can fix it. (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 steps are all the more critical.)
• Create a new user and put the items required to see the bug together on a single menu. If we have to search a dozen menus containing 30 choices each, that is only going slow us down. Don’t put menu items in hierarchical menus — unless the bug is related to hierarchical menus! If you are reducing an existing collection to send to us, delete all of the existing users and create just one user so we can log in quickly. And please do not put a password on it. Nothing is more frustrating for us than to gear up to work on a bug only to be stopped because we can’t get in to the collection.
• Put command keys on all relevant menu items. Make F5 the ‘first keypress’ so that anybody working on your bug should be able to open your collection and press F5 to get started.
• 
  Document the bug directly in the collection.. Put the instructions right on the view that opens when F5 is pressed. By putting instructions there, you guarantee that the person looking at the bug has everything they need to understand the bug presented to them right there, with no need to refer to external documentation at all. Include screen shots of relevant structure to the view, or in an auxiliary view. Do not send us a collection without self-contained instructions! Please remember that you know your collection intimately, while we have never seen it before. Sending a collection with vague instructions such as ‘run the end of month summary report’ may mean something to you, but it is only going to result in delays. Click the screenshot on the right to see a well-documented view.

When documenting a collection, refer to items by exact name, not by menu position. You should write: “choose ‘Data Entry’ in the ‘Testing’ menu,”, not “choose the first item in the testing menu.”

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 10MB, attach it directly to your bug report in techdb, our customer support database. The Support Documents section of the bug report form is designed for this very purpose. (For instructions on how to attach a support document, see the How to Send Crash Logs page.)
2. If the collection is larger than 10MB, 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 might be 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. 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 as you see it; 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.