Everything Else
How To Report Bugs & Request Features via techdb

This is a guide for using techdb for the purpose of searching existing bug reports, submitting new bug reports, making feature requests, and participating in community discussion about bug reports and feature requests.

You are encouraged to visit techdb frequently and to comment on reports that are of interest to you. The discussion section of each report is our primary method of communicating about these reports. If we have questions or comments about a report, that is where the discussion takes place.

Accessing techdb

The first step is (obviously) to log into techdb. If you are not familiar with this resource, the main techdb page provides step by step instructions on how to connect and how to become a registered user. (Only registered users are able to submit reports and contribute to the discussion on existing reports.)

The Reports & Searches Menu

Report Menu Once you are logged in and registered, the various report views are found in the Reports & Searches menu. The Report Index lists the reports that have already been entered, and Report is the entry view you use to create new reports.

There are many ways to search the existing reports:

  1. Report Index is a simple list with a Power Query that can be used to filter the reports.
  2. Search Reports is a typical host/subform search that uses keywords to restrict the report. The search field supports up to three distinct words, which are joined via and logic. For example, typing post dialog crash will show only records where all three of those words are found in the subject, summary, and discussion of the report. This form also has a popup menu that allows you to limit the reports to certain status levels. Chances are you do not want to see only currently reports, ignoring those classified as ‘Fixed’, ‘Not A Bug’, etc. This popup lets you focus on the current reports, or to expand your search to include every report in techdb.
  3. Search Reports (‘Or’ Query) is a typical host/subform search that uses keywords to restrict the report list. The search field supports up to three distinct words, which are joined via or logic. For example, typing post sequence will show every record where either of those words are found in the subject, summary, and discussion of the report. This is less useful, as the results will be quite long, but it can be helpful if you need to broaden the search. This form has the same ‘status level’ filter as the previous form.
  4. Recently Updated Reports restricts the subform to show only reports created or modified after a specific date. You can also enter your customer number and access password to further restrict the list to show just the reports you created. The ‘status level’ filter (described above) refines the list further.
  5. Find My Reports restricts the subform to show only reports you have created or contributed to the discussion on. The ‘status level’ filter (described above) refines the list further.
  6. Find My Documents is a list of documents you have attached to reports.
  7. Feature Requests is a simple list queried to show only records whose current status is ‘Feature Request’. This list is typically short, as entries are moved to another status. (‘Open for Discussion’, ‘Assigned’, ‘Fixed’, etc.)
  8. Known Problems is a simple list queried to show only records that cover issues that have not yet been fixed. This covers reports whose status is ‘Known Problem’ as well as ‘Assigned’, ‘Confirmed’, ‘Deferred’, ‘Fix Committed’ or ‘Fix Pending’. This form also has a query attached that can be used to further refine the list.
  9. Europa Reports (Helix 6.2) & Callisto Reports (Helix 7.0) restricts the subform to show only reports created for those specific versions. You can also enter your customer number and access password to further restrict the list to show just the reports you created. The ‘status level’ filter (described above) refines the list further.

Lastly, a hierarchical menu allows you to search the Error Codes Helix displays when a collection crashes. This is fairly technical information of limited use.

Bug Reports vs. Feature Requests

Some companies separate Bug Reports and Feature Requests into two separate categories, with separate processes to handle them. But if you think about it, they come down to the same thing: “it doesn’t work the way I want it to.”

feature_request Consequently, whether you are filing a bug report or a feature request, you use the same form in techdb. It’s called Report and it is shown in detail below. Within that form, the Report Type popup menu (shown at right) has a choice for feature requests; specify your report as such and it will be added to the request list.

The Reports menu (see above) has a list specifically queried to show just feature requests. Please review the list before you add a new request. If your request is already there, or is there in a slightly different form, add a comment to that report voicing your support and/or your similar suggestion.

Filing a Report

Once you have determined that your report is brand new, and nobody has reported it before, you should create a new report.

Since this is Helix, filling out an entry view should be second nature to you. Nonetheless, a bit of guidance may prove useful. The form is divided into sections, with common fields grouped together…

  1. Customer Info: Who you are. You must supply your customer number and access password to create or modify a report. When you enter this information correctly, the two buttons (mid-way down the form, on the right side) activate so that you can enter/modify the record. (The default button simply does a Static Enter, but its label gives you guidance regarding what is missing or what triggering it will accomplish.)
  2. Helix Product: The product for which you are creating this report. Specify the product and the build number. Check the About Helix… window if you are not sure which version you are using. You must supply a product and build number to create a new report. (For feature requests, choose ‘N/A’ for the build number.)
  3. System Info: Tell us a little about the Mac model and OS version you saw the bug on. Very seldom is a bug machine specific, but supplying that information may help us identify such a situation.
  4. Report Details: What sort of issue you are seeing. There are fields for specifying the type of problem (crash, cosmetic bug, feature request, etc.) the severity, whether it happens every time or not, and of course, a subject for and summary of the bug. Please try to make the subject short, but descriptive in a broad sense. When other users are searching the database for reports, you want them to be able to know what this bug is about just by reading the subject line.
  5. Collection Information: If you are reporting a bug that is found in a specific collection, and you can not reproduce it in a new collection, tell us a little about the collection here. Most important is whether or not you can send a copy of the collection to us, upon request. Bugs can seldom be fixed unless we can see the bug in action. The fastest way for us to see the bug is for you to send us a collection that shows it. (But don’t automatically send it; just let us know if we can have it when we need it.)

Once you have created a new report, you can then enter additional information to support our efforts. (Click the image to see a full-size version.)

  1. Support Documents: If you need to send us files to help us fix a bug, this section attaches them directly to the report they relate to. You can attach crash logs and sample collections, but please don’t send screenshots of error dialogs. That is just a waste of space: report the contents of the error message in the Report Details section instead. Likewise, pictures of views with problems aren’t particularly useful; chances are it will just look like a Helix view to us and mean little. (For instructions on how to attach a support document, see How to Send Crash Logs.)

    Note: if you are attaching a larger file (such as a sample collection), be sure to archive it first, to save space. If your attachment is larger than 10MB, you won’t be able to attach it directly to techdb; instead, use the instructions on the Collection Damage and Repair Options page to upload your file(s) to our collection repair server.

  2. Discussion: This is the fun part. Everybody can join in on the conversation about your report. Maybe somebody else has seen this bug, and maybe they have found a workaround that will help you get past it until we can fix it. Or maybe your feature request will trigger a thought for another user who has an idea that makes the request even better.
  3. Importance Votes: You are encouraged to vote on how important you think a particular report is. If many users tell us something is very important, we will pay attention. Our decisions are not based solely on user popularity, but that does have influence. Votes are on a scale of 0-100.
  4. Internal: If there is sensitive information you need to convey to us about the report, this is the place to do so. Only QSA ToolWorks (and you) can see this information.
macOS: Crash Logs Tell the Tale

attachmentsIf your report is about a crash in a Helix product, the macOS Crash Log can give us a great deal of detail about what went wrong in Helix. After you have created the initial report, you can then attach your crash logs in the “Support Documents” section of the Bug Report form. If you submit a report related to a crash, please follow through with this important step.

The macOS Crash Logs page explains how to find the crash log and gives you more details about it.

Reviewing a Report: Report Status

Your responsibiltiy does not end once you have filed your report. The Status field (at the top of the entry view) tracks its progress through our system. When you create the report, the status is set to New. When we review it, we change the status to reflect our initial thoughts. The status can change to:

  1. Waiting for Review: We have seen the report, but it requires more thought to properly categorize it.
  2. Info Needed: We need more information from you.
  3. Internal Testing: We have put it on the schedule to try to reproduce it.
  4. Confirmed: We have successfullly reproduced the bug.
  5. Open for Discussion: Before taking action on this report, we need to hear more from our customers.
  6. Assigned: The bug is assigned to one of our engineers.
  7. Fix Pending or Fix Committed: We have fixed the bug, but have not yet tested it fully. These are interim stages between the time an engineer fixes a bug and technical support receives the code and confirms that the fix works.
  8. Fixed: We have fixed the bug with high degree of confidence. Next to the Status field will be the version number where the bug is fixed.
  9. Retest: We think this bug is fixed, and want you to retest it. Next to the Status field is the build number where we think the bug is fixed.
  10. Waiting for Another or Works for Me: We can not reproduce this bug and it appears to be a highly isolated case. We don’t want to dismiss it outright, but there’s not enough solid evidence to move it forward.
  11. Deferred: We have successfully reproduced the bug, but we will not be addressing it immediately.
  12. Known Problem: This is already cataloged in the Known Problems section of our release notes.
  13. Specification: The report asserts that a behavior is incorrect, but that behavior is actually the way Helix is designed to work.
  14. Not a Bug: The behavior described is not considered buggy. Helix is performing as designed.
  15. Can’t Fix: This is something we can not fix, probably because of a limitation in macOS or wxWidgets.
  16. Won’t Fix: This may be a bug, but we are not going to address it. This is most common for bugs in older versions (such as Classic Helix) or for areas of the code that are slated for a larger overhaul in the future.
  17. Duplicate: There is already a report for this bug. The original report number will be found in the Discussion section.
  18. Invalid: This report makes assertions that are just plain wrong, such as claiming that Helix has a limit of 20 fields per relation. More often, these are requests for ‘new’ features that have already been implemented.
  19. Closed: This is most common when a issue has been addressed some time ago, and want to keep it from appearing in searches for active reports. Closed reports can not be modified.

If the status change requires that you take further action to help us, please do what you can. The more you can do to help us isolate the bug, the faster we can fix it.

Beyond the Report

Reporting (done properly) requires ongoing effort. We need you to work with us beyond the initial report. Check in on a regular basis and monitor the status of your reports. And when we think we have addressed your report, test to make sure we’ve done so to your satisfaction.

Fixing bugs and developing new features is a community effort; feel free to contribute to the discussion for other user’s report. We don’t intend for each report to be a conversation strictly between QSA ToolWorks and the reporter. The more Helix users who can provide pertinent discussion, the better our chances addressing it in the best way possible. (And of knowing when our fixes really fix the bugs!)

For Further Study

The How To Get Your Bug Fixed page.

The Writing Good Reports page.

Reference Material

For another perspective on making your reports more valuable see this insightful article by Brett Simmons (creator of NetNewsWire, back in the day).