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 macOS. 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 macOS. 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.’

If you’ve found a bug, your first response should not be to send us your 200MB 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 demonstrate the bug in a collection created from scratch, you’ve got a bug we can fix in hours, not days.

If you can reproduce the bug in small sample collection that shows the bug and contains instructions right in the collection itself, you have guaranteed that you will get our immediate attention.

But sometimes a new collection built from scratch doesn’t show the bug, or building such a sample is impractical. We still need a sample that shows us the bug as simply as possible, so the next step is to reduce your collection until it is as simple as possible and the bug is neatly isolated.

To some, the prospect of ‘disassembling’ a complex collection is a daunting task, but we hove found that even the most complex collections can be reduced in just a couple of hours, particularly by leveraging the power of AppleScript.

If you are about to take on the task of reducing a collection to show us a bug, these guidelines can help you reduce a collection, and to present us with the best possible chance of fixing your bug quickly. The following steps are written from the perspective of isolating a bug that is seen when working in ‘User Mode’ (as opposed to Design Mode bugs seen in the Inspector, etc.) but either way, the principles are the same.

1. Make a copy of the collection. This goes without saying, but beyond that, we suggest that you name the copy something like sample 00 and then, as you make progress in isolating the bug, you make additional copies named sample 01, sample 02, etc. Chances are the bug will disappear at some point, and having partially reduced copies to go back to is much better than re-starting from the beginning. The ‘Make Iterations (Duplicate and Rename)’ AppleScript on our free scripts page (in the ‘Non-Helix’ section) is a drag and drop applet that does this automatically.

2. Determine whether the bug appears in Helix RADE, or only in Client/Server (or Engine). If the bug appears in Helix RADE — and even better, in Design Mode — it is both faster for you to reduce it and faster for us to study the bug in action.

3. Determine whether data is necessary to see the bug. If the bug appears simply by choosing a menu item or clicking a sequence button, it may be that the same bug will show even with no data in the collection. The ‘Delete Relation Data’ AppleScript on our free scripts page (in the ‘Working with Data’ section) makes it easy to quickly delete data from a collection. If it makes sense, reproducing the bug with no data in the collection is a good way to quickly reduce the size of a collection (and ensures that your data remains private).

4. Create a new user and put only 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. 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. This also eliminates the need for you to give us your user password. And while we’re on the subject of passwords: if there is collection password, remove it! We promise to guard your collection and it’s data zealously.

5. Put command keys on all relevant menu items. Make F5 the ‘first keypress’ — hopefully opening a view that contains instructions on how to see the bug. No matter where it leads, anybody working on your bug should be able to open your collection and press F5 to get started.

6. Strip the template down to only what is necessary to see the bug. No doubt there is something on it that is irrelevant to the bug. Remove it. Debugging a problem on a view with 5 rectangles is significantly faster than on one with 100. This step often reveals details about the bug that allow you to create a workaround until we can fix the underlying issue, and sometimes provides surprising revelations that show our early speculations on the nature of the bug were just plain wrong.

7. Internal Documentation

   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.

   Instructions can be placed on the template you stripped down in the prior step, or make a new template & view specifically for showing the instructions. Either way, do not send us a collection without self-contained instructions! Please remember that although you know your collection intimately, we have probably never seen it before. Sending a collection with vague instructions such as ‘run the end of month summary report’ may mean something to you, it leaves us guessing (and wasting time). Click the screenshot on the right to see a well-documented view.

8. Lock the icons needed to see the bug. The steps in removing unrelated structure are repetitive and can often lead to accidentally deleting structure that already known to be relevant. Lock the User icon you created in step 3 above, and lock the view that shows the bug. If the view is locked, none of the icons it refers to can be deleted, so that is really all the locking that is necessary. (If you created a separate documentation view, lock it too!)

9. Delete unneeded icons. 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.

   In a complex collection, this is the step that is most time-consuming, and we have found that AppleScript helps greatly here. We have developed a number of scripts that we are happy to share with you, so contact us if you are ready to reduce a collection and want to proceed as efficiently as possible.

   To remove structure manually, start in the main collection window: switch the view to list mode, select all of the sequences (click on the first one, then shift-click on the last one), and try to delete them. Some won’t go because they are in use, but some will. Every little bit helps at this stage. Next select all of the relations, switch them to list mode — this will definitely make the task easier — and open them. (Command-O to Open and Command-W to Close are your friends!)

   Now it gets repetitive: Starting with the top most relation window, select the everything from the abaci down through the posts. (Again: click on the first icon, then shift-click on the last icon to select them all.) At this point you have everything except the fields selected. Press Command-delete to delete the selection. As with the sequences, not everything will be deleted, and that’s OK. Close that relation and do the same with all of the rest. Since you deleted all of the regular user icons in step 3, most of the views will go, along with many templates, queries, and posts.

   After all of the relations have been processed, go back to the sequences — many more will be unused at this point — and try to delete them again. Then reopen the relations and repeat the process. Each time more and more irrelevant structure will be eliminated.

   Oh, every so often stop, make another copy of the collection, and retest to make sure the bug hasn’t disappeared!

   If you want to really speed up this process, take a break from the repetitive loop and open the templates that are irrelevant to seeing the bug, select all rectangles (Command-A), delete them, and close the template. It’s a meaningless template now, but it has nothing to do with seeing the bug, deleting these rectangles will free up many more sequences, subform templates, and abaci containing lookup and use from tiles.

   After that there may still be a few odd cases where an irrelevant icon is still in use somewhere, but now the quantity of those is small enough that using ‘Get Info’ to find those references is not a problem.

10. Delete irrelevant data. Although it might seem logical to start by deleting data — since most of the size of a typical collection is in the data — it typically (the exception is noted above) should not be done until the bug is isolated in the structure. (When we say to ‘reduce’ a collection we are referring to its complexity as much as to its size.)

    Once the irrelevant structure is eliminated, any field that is not involved in the bug will be marked as unused and ready for deletion. You can delete them one by one, clicking the confirmation dialog each time, but there’s a better way: identify the relations where all fields are no longer used and delete the relation entirely. You’ll have a single warning dialog to confirm and then the relation and all of its data are gone.

    For relations that do have icons related to the bug, you can probably still delete some of the fields. If you don’t have an AppleScript to do this, you’ll have to answer a dialog for each field, but even so, it’s a quick process.

11. Reduce collection size After the collection has been reduced as much as it can be, while still demonstrating the bug, use Helix Utility to compress the collection. Your 200MB collection is now much smaller and easier to transport, and we can focus on the bug with minimal distraction.

    Actually, compressing the collection during reduction process goes a long way to making the whole task go faster. In Step 1 we suggest making ‘partially reduced’ copies throughout the process. One excellent way to do this is to use Helix Utility to make a compressed copy each time, replacing the default ‘(compresed)’ text with the next number in the sequence.

Yes, it can be a lot of work to reduce a bug to its smallest possible size, but remember that the more you do to make it easy for us to see the bug, the faster we can fix it. And if anecdotal reports are of any value, our users seem to find great satisfaction in helping in this way, and sometimes they even learn things about their collection they can use to make it better.

If attempts to trim it down fail, then by all means send us the whole collection. We’d prefer that you contact us first so we can help you reduce it further, but at the very least, follow step 4 above to create a new user with no password and only the menu items we need to see the bug. Either way it is critically important that you accurately document the steps needed for us to see the bug. When documenting a collection, be sure to refer to items by exact name, not by menu position or other loose criteria: “Choose ‘Sales Summary’ in the ‘Reports’ menu,” is far better than “Open the first report.”

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

Start by making a .zip archive of the collection, along with any relevant files (import files, etc.). Name this archive in a way that will help us match it to your report. If you’ve crated a report in techdb, name the zip archive ‘Rnnnn.zip’ where ‘nnnn’ is the report number. Otherwise, name it ‘Cnnn.zip’ where ‘nnn’ is your customer number. (You can also add a word or two to help identify is, such as ‘R9999-Abacus Error.zip’)

1. If the zip archive 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 zip archive 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, use your bug’s R (report) number or your C (customer) 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 macOS Crashes page to get the crash log and attach that as a supporting document to your beta report. Again: No Screenshots!

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.