Eliminating Every Bug
Manifold users are strongly encouraged to send in bug reports if the product does not perform as described in the user documentation. Every Manifold update includes bug fixes that have been prompted by user reports. Every bug report is considered carefully - Manifold has a zero tolerance policy on bugs.
New bugs are very rare. Most bug reports, especially those filed by beginners, are not traced to real bugs but instead arise from errors in concept or operation. That's OK. The Manifold team would rather receive and review all bug reports to make sure that no real bug gets overlooked.
The following guidelines will help increase identification of real bugs and will help users choose whether messages they would like to send should be sent in as suggestions, as bug reports or as requests for technical support.
Bug Report, Suggestion or Tech Support Question?
If the product does not do something as it is explicitly documented in Help, that's a bug. If it does not include a feature or capability you would like to see, or if it is missing opportunities for additions here or there that might expand the usage of an existing feature, or if it does something in a way not to your liking, that's a new feature suggestion. For tips on sending in effective suggestions, please see the Suggestions page. Manifold encourages users to send in all suggestions, large or small.
Bug reports do not contain questions. If you have a question on any matter, that's a tech support question. See the Support page and the Contacting Tech Support page for information on getting tech support questions answered.
Please Note: Any email message sent in as a bug report that contains a question will get routed by heuristics to the technical support incident processing system. Please do not ask rhetorical questions or use the question mark "?" character in a bug report. If you would like a reply to a bug report, such as confirmation whether it is really a bug or not, please include an appropriate tech support token.
Quick Checklist for Bug Reports
Finding a bug is like finding a needle in a haystack. That process can go more efficiently if bug reports provide enough information to identify and eliminate bugs. Some basics:
- Please write in English and use a subject line that includes the words "Manifold" and "bug report" to assure your email will not accidentally be intercepted by spam filters enroute. Please include the phrase "No reply expected" somewhere in your email to make it clear you do not wish to ask a tech support question.
- Describe your hardware: What processor, how much RAM in the system, how much disk total and how much free disk space? Are you physically present at the machine or are you remotely accessing the machine from somewhere else?
- Describe your software: Are you using any virtualization software? What version of Windows? 32-bit or 64-bit Windows? What Manifold Edition? 32-bit or 64-bit Manifold? What is the Manifold version number reported in Help - About?
- If you are not using the very latest Manifold update from the Updates page, please download and install the latest update and verify the bug still exists. If so, submit the bug report using the latest update. Bug reports for releases other than the very latest update cannot be investigated.
- Give a detailed description of the problem, including your workflow. Describe every dialog you used and the settings used. If you had a problem after importing some data set, what were the steps you followed? What dialogs were used and what were the settings?
- Describe the data set you used. If you can reproduce the bug (ideal!) using a data set that can be downloaded from the manifold.net web site, what is the URL to the data set and what are the steps to reproduce the problem?
- Please use ordinary text format for your email, not HTML email, and write all of your bug report in the ordinary text. Do not use attachments except for small (2 MB or less) Manifold .map files. Please do not attach .doc, .pdf or other files containing text. If a sample file is requested, Tech Support will provide upload instructions to upload the files by FTP.
- Please email bug reports to firstname.lastname@example.org. Do not cc your communication with tech support with any other email address.
Tips for Effective Bug Reports
Some tips on how to contribute productive bug reports that will improve the product as rapidly as you would like:
- Don't ask rhetorical questions. Bug reports should not assume replies so don't make the intake process try to guess when you are seriously asking a question and should be passed to tech support or when a question is just a rhetorical question to which you don't expect a reply.
- Do not combine tech support questions with bug reports. If you have business with tech support, take care of that in an email thread dedicated to that business. If you have a bug report, take a moment to compose a separate email message so your report will not be confused with a tech support transaction.
- Don't call a suggestion for a new feature a "bug report." For example, comments of the form "I've found a terrible bug in Manifold - it doesn't include a full-featured word processor like Microsoft Word" are a good way to lose credibility. If you want something new, send it in as a suggestion: Have faith that a clear suggestion saying what you want will have impact. For tips, see the Suggestions page.
- Don't join a herd: if you don't have direct, personal experience of a problem don't report something you've heard on Internet. Second hand reports reduce credibility and increase noise that makes it harder to find those rare bugs that are real.
- Please provide all necessary information in your bug report. Don't refer to Internet threads or the comments of other people, as those may have changed or may not be clear. Engineers will not attempt to parse a discussion thread to guess what might be the problem - if it is a real problem they know from long experience it will be reported.
- If you are new to the product, don't jump to the assumption that something unexpected is a bug. Research the documentation carefully. Take a moment to talk out your ideas with friends, perhaps by posting to the Manifold community forum at http://georeference.org to see if you've missed something already in Manifold. If some preliminary exploration shows the problem might be a real bug, please send it in.
- Don't worry about looking dumb or missing something obvious in Help. Please don't hesitate: send in a bug report. Everybody knows most bug reports aren't really bugs. That's OK. At a minimum, your report may indicate the need to improve Help in that subject. If you've overlooked something - no harm done. All reports are received with gratitude for the time you spend sending them in.
Ground Rules for Bug Reports
Please email bug reports to email@example.com. Bug reports will be acknowledged but will not usually receive a personalized reply. However, all letters conforming to the guidelines in this page are noted and will be investigated for potential bugs. In addition to the above basic tips there are several general rules which apply:
- Please keep it technical. The mission is building a better GIS package for the Manifold user community and that has to do with specific technical features. Focus on writing a clear and detailed technical bug report in a purely objective technical manner. Non-technical comments, earnest flames, political rhetoric, etc., will only interfere with the investigation of a bug report.
- Do not send any bug report, suggestion or comment that you do not wish to become a part of the public domain, that is, freely usable by anyone without any control by you or compensation to you. All bug reports or comments received by Manifold enter the public domain and are not confidential. Do not send any information or communication to Manifold that you want to remain your intellectual property. If you send it to Manifold you are giving permission for that bug report, idea, suggestion or other comment to be used any way that Manifold desires, including free publication onto the web for anyone else to use and also including sale to a third party, without any compensation to you or intellectual property claim by you. If you work for someone else, do not send any bug reports, ideas, information or suggestions that do not belong to you or that are not already in the public domain.
- Not all bug reports will receive personalized replies, but at times you may be contacted by Manifold personnel to discuss your bug report. If so, any such communications are not a guarantee that your bug report indicates a real bug or that corrective action will be taken or when such action might be taken. Do not base your purchase decision of additional Manifold licenses on an expectation that any changes may be made to the product based upon a bug report you have submitted.
Frequently Asked Questions
Does sending a bug report count as a support incident? Not unless it is embedded within a support request or if a reply is requested. Example: "How do I thematically format a drawing using a text field in the sort order I desire? Is this a bug I can't do it?" This will be treated as a request for support and will require a support token.
What if my continued use of Manifold is dependent upon the fix of a bug I have reported? You should never acquire licenses based on anything other than the capabilities of the released product. A corollary to that is you should never acquire licenses based on anything than the usage your skill level, time and resources can get out of the product.
How do I find out the status of a bug report? Once a bug report is made there is no way to tell the status until it appears in an update to an existing release or in a new release. Manifold is grateful for all bug reports but is unable to provide reports of whether or not specific bug reports have resulted in a new bug and if so, when a fix may appear in the product. Tech support will often acknowledge the finding of a new bug with the original reporter, but that may not be possible in all cases. If you need a report for sure of the result of a bug report investigation, submit the bug report as a request for tech support with the appropriate token.
Why are not bug reports on the online user community forum monitored? There are two main reasons. The first is that this policy reserves for the forum the freedom of having informal conversations and "thinking out loud" before sending in a bug report. Experienced users like to consult with their colleagues and want to be able to discuss an issue casually without triggering an engineering investigation. The other main reason is that much speculation on Internet forums is woefully inaccurate. People take more care when composing a real bug report, so focussing on those reports judged important enough by users to send in as a bug report results in much higher quality reporting. New users can learn from more experienced users via online communities as well: quite a few bug reports will turn out to be simply a lack of experience and not realizing how to operate the product correctly.
Testing out such ideas in the forum is a good way for new users to benefit from the knowledge of their more experienced colleagues.
Advice from Technical Support
As much as bug reports are appreciated, users should not let the consideration of a possible bug lead them astray if they have encountered a problem. Few things are as effective at stopping the solutions process as deciding too early on that the problem must be a bug. Do not allow assumptions about a possible bug to prevent you from taking effective measures to solve problems.
Bugs are very, very rare. It is almost always a mistake to think that a problem arises from a bug and not from an error in concept or operation. If you have a problem, hit the books and apply your maximum RTFM skills. Beginners will at times leap to the conclusion that the problem they are experiencing is caused by a bug in Manifold. Anecdotal evidence indicates that the less carefully someone has read the documentation, the more likely they are to leap to such a conclusion. This is almost always a mistake, as bugs in Manifold are very rare and are almost never found by inexperienced users.
If you have a problem, focus your energy on a detailed understanding of what you would like to do and on a very diligent and detailed reading of the Help topics that are relevant. If you need assistance, don't hesitate to contact tech support as set forth in the Support page, but leave it up to tech support to run down the problem. The possibility of a bug is always kept in mind by tech support so leave it up to tech support to determine if a bug is the source of the problem. This even tech support cannot determine without lots of detailed information so careful attention to what you are doing is necessary in any case.
It's true that on rare occasion there are new bugs found as a matter of happenstance by beginners. If you are a beginner, don't let that rare statistic distract you from the more likely possibility of a nuance missed or some useful documentation misunderstood. Send in a report if you suspect a bug, but at the same time keep applying your RTFM skills, discussions with friends and, if need be, contacts with tech support for assistance.
Suggestions to improve Manifold are always welcome. Please see the Suggestions page for tips on making effective suggestions.